Detailed Planning Files

This section describes in detail the files used and exchanged during the Detailed Scenario process.

These files will be exchanged and used using the JUICE SOC Pre-operational Git repository: JUICE_PREOPS). More precisely, using the Git branch dedicated to the scenario.

During the Detailed planning exercise, the following files will be exchanged between the PI teams and the SOC:

  • Observation Timeline Harmonisation

    • Observation Definition File (ODF)

    • Event Definition File (EVF)

    • Observation Plan (OPL)

  • Pointing Timeline Harmonisation

    • Observation Definition File (ODF)

    • Event Definition File (EVF)

    • Pointing Timeline Request (PTR)

    • MAJIS SPICE CK Kernels (CK)

    • SWI Pointing Table (SPT)

  • Instrument Timeline Harmonisation

    • Observation Definition File (ODF)

    • Instrument Timeline (ITL)

    • Event Definition File (EVF)

File versioning and deliveries

In the definition of each file, a description, the generation process, the name convention, and the delivery mechanism are described.

For all these files, the versioning follows a tailored format that allows to identify the author of the file and the iteration of the file. The versioning is based on the following format:

<file_type>_<ins>_<scenario_id>_S<xx>P<yy>.<ext>

where

  • xx: is the SOC delivery version, e.g.: 01 for the first SOC delivery.

  • yy: is the PI team delivery version based on the xx SOC delivery, e.g.: S01P02 is the second PI delivery based on the first SOC delivery.

e.g.: OPL_JAN_S007_01_S01P02.json this is the second PI delivery of the OPL file by the JANUS team P02 following the first delivery from the SOC S01.

Typically the SOC will deliver the xx version of the file, which corresponds to the 00 iteration and the PI teams will reply to it by incrementing the yy number. xx will be incremented by 1 for each delivery of the SOC whereas the yy number will be reset to 00 for each new xx delivery.

In addition, for each file there will a copy of the latest S<xx>P<yy> version in SXXPYY which will be the version loaded by the PHS (MAPPS or OSVE).

Each file type follows a different delivery versioning timeline; i.e.: not all the delivered file types need to follow the same S<xx>P<yy> versioning. In general these versions are aligned per file type or per period of the planning exercise.

Note

Please note that by convention all the directories and filenames are in upper case except for the file extensions that are lower case. This is due to historical reasons and the upper case is kept because it facilitates the comparison of filenames given that the vertical size of the letters is always the same.

Observation Plan File (OPL)

OPL files provide a list of time-ordered observations per instrument or for multiple instruments and are used and exchanged by the SOC and PI teams during the Observation Timeline Harmonisation (OTH).

OPL files description and their naming convention are described in [PICD], the latest working version definition is available at PSICD_0102: Observation Plan File (OPL, single instrument).

During the OTH process the following OPLs will be made available by the SOC under the TIMELINE directory, e.g.: PLANNING/SCENARIOS/S007_01_PJ12_320922_320926/TIMELINE/OPL_SOC_S007_01_S01P00.csv

  • OPL_SEG_*: Segmentation Level observation plan, not strictly observations but handy to track the blocks from the segmentation.

  • OPL_OPS_*: Observation plan with operational blocks, i.e. TMCs, WOLs, Downlinks, S/C flips, and Optical Navigation.

  • OPL_SOC_*: Observation plan that includes all the timelines.

  • OPL_PRI_*: Observation plan including all the PRIME observations.

  • OPL_DES_*: Observation plan that includes the DESIGNER blocks.

In addition, and especially for the first deliveries, the OPL files delivered by the SOC will also contain the initial RADEM and NAVCAM observations as separate OPLs (PSICD_0104: NAVCAM/RADEM/JMC Observation Plan File (OPL))

OPL Generation

The SOC has put in place a procedure that is described hereunder in order to assist the generation of ASCII OPL files, this procedure is not mandatory and is not meant to replace any internal procedure or scheduling process produced by the instrument teams.

ASCII OPL generation can be assisted by the SHT Timeline Tool CSV export functionality as described in OPL Generation with the Timeline Tool.

OPL Delivery Mechanism

SOC Deliveries

OPL files are delivered via direct merge by the SOC after each meeting of the Observation Plan Harmonisation process. The Direct Merge mechanism is described at SOC->PI Deliveries

The delivery directory within JUICE_PREOPS is: <scenario_name>/TIMELINE. E.g.: Delivery the SOC OPL file for the PJ12 Scenario at: PLANNING/SCENARIOS/S007_01_PJ12_320922_320926/TIMELINE/OPL_SOC_S007_01_S02P00.json

PI Deliveries

OPL files are delivered via merge request mechanism by the PI teams before the specified deadline within the Observation Plan Harmonisation process. The Merge Request mechanism is described at PI->SOC Deliveries

The delivery directory within JUICE_PREOPS is: <scenario_name>/TIMELINE/<ins>. E.g.: Delivery of the JANUS OPL file for the PJ12 Scenario at: PLANNING/SCENARIOS/S007_01_PJ12_320922_320926/TIMELINE/JAN/OPL_JAN_S007_01_S00P01.json

Observation Definition File (ODF)

Observation Definition Files are used and exchanged by the SOC and PI teams during the whole Detailed Scenario process (OTH, PTH, and ITH). Depending on the phase, only certain parts of the ODF files can be updated.

ODF files description and their naming convention are described in [PICD], the latest working version definition is available from PSICD_0101: Observation Definition File (ODF)

Important

Please note that the times defined in the Observation Definitions are relative and will be resolved with respect to the times provided in the corresponding Instrument Timeline file (ITL) that provides the start and end times of the observations.

ODF Generation

ODFs are initially generated automatically by the SOC using internal tools from the Observation Definitions in the JUICE SOC Observation Database.

The observation database is used to export the Observation Definitions used as input files for the process. Updates in the Observation Database can be accommodated before the start of the exercise and are preferred to later updates of the Observation Definitions, especially if these updates are applicable to all the observations of a given instrument and are not particular to the scenario that is being worked on.

Later updates of the Observations that need to be fed back into the database will be performed at the end of the Detailed Scenario Process and should be thoroughly documented by the Instrument teams in their final report.

The initial SOC-generated ODFs are placed under the directory <scenario_id>_/DEFINITIONS/OBSERVATIONS/<ins>/GLOBAL directory. In addition, if the science segments are linked to certain observation, these observations will also be made available at: <scenario_id>_/DEFINITIONS/OBSERVATIONS/<ins>/SCENARIO

Generation of Instantiated Observations

Alternatively and during the Observation Timeline Harmonisation process, ODF files can be created or updated manually to generate the scenario instantiated observations from the parent or global observations.

These instantiated observation must have a parent observation type from an ODF present in the GLOBAL directory (as it comes from the JUICE SOC database) and their name can be extended with a description for the particular instantiation.

The PI-updated ODFs are delivered under the directory <scenario_id>_/DEFINITIONS/OBSERVATIONS/<ins>/SCENARIO

These instantiated observations will not be fed back into the JUICE SOC Observation Database as they are considered children or instantiation of currently existing observation types from the database.

ODF Delivery Mechanism

SOC Deliveries

The SOC provides all the Observation Definitions available at the JUICE SOC Entity Database at the kick-off of the Detailed Scenario exercise in the following directory: <scenario_name>/DEFINITIONS/OBSERVATIONS/<ins_name>/GLOBAL

Only the files with SXXPYY versioning are provided in that directory.

In addition, the observations that are linked to the segments of the scenario are also provided by the SOC on the following directory: <scenario_name>/DEFINITIONS/OBSERVATIONS/<ins_name>/SCENARIO

These files provided by the SOC include the version S00P00 of the files along with their SXXPYY duplicates.

PI Deliveries

Instrument Teams can provide ODF updates via merge request mechanism before the specified deadline during the Observation Plan Harmonisation process. These updates can include the PTR block and the ITL blocks within the ODF.

During the Pointing Timeline Harmonisation, the Instrument Teams can only provide ITL blocks updates for the ODFs. At this stage the PTR updates will already be performed with the PTR files; PTR blocks within ODFs will not be considered for integration in the PTR.

During the Instrument Timeline Harmonisation, the PI teams can only provide ITL blocks updates for the ODFs as an alternative to providing ITL files.

Important

The delivery directory within JUICE_PREOPS is: <scenario_name>/DEFINITIONS/OBSERVATIONS/<ins_name>/SCENARIO PI teams cannot deliver files in the GLOBAL directory. Only the numbered versions S<xx>P<yy> e.g.: S00P01 are provided, the update of the SXXPYY is performed by the SOC. In addition, PI teams do not need to update the top level ODF files such as: <scenario_name>>/DEFINITIONS/OBSERVATIONS/JAN/ODF_SCENARIO_<ins>_<scenario_id>.def

Pointing Timeline Request File (PTR)

PTR files are used and exchanged by the SOC and PI teams during the Pointing Timeline Harmonisation.

PTR files description and their naming convention are described in [PICD], the latest working version definition is available from PSICD_0200: Pointing Timeline Request (PTR)

PTR Generation

PTR files, or rather Observation blocks within a PTR file, can be generated with the assistance of the JUICE Pointing Tool, the Pointing Tool Wrapper, the JUICE Cosmographia Plugin, or with the esa-ptr Python package.

You might find the documentation of these tools useful for PTR generation: JUICE SOC Toolkit Documentation.

Typically, you will need to generate or design a PTR OBS block by updating an already existing block. Be aware that you need to keep all the information specified in the syntax section.

More guidelines on how to generate PTRs are available at PTR Generation Guidelines and Rules.

Baseline PTR

The baseline PTR is the result of updating the skeleton PTR that is coming from the trajectory segmentation. The skeleton PTR is generated by the predefined attitude that certain segments have such as Jupiter Nadir Power- optimized for the Tour out of flybys, Moon tracking Power-optimized for Optical Navigation, etc. The PTR snippets present in certain segments can be found in the Segment database.

However, during the OTH process, the baseline attitude may be updated, depending on the expected “general” target of the period, i.e.: during the inclined phase there the baseline attitude can be agreed to be tracking the North Pole with a given phase angle.

PTR Delivery Mechanism

SOC Deliveries

Initial, or baseline PTR files, along with harmonised PTR files are delivered via direct merge by the SOC during the Pointing Timeline Harmonization process.

The delivered PTR file names will be restricted to PTR_SOC_<scenario_id>_S<xx>P<yy>.ptx each delivery will be made along an update of the SXXPYY file.

The delivery directory within JUICE_PREOPS is: <scenario_name>/POINTING.

PI Deliveries

PTR files are delivered via merge request mechanism by the PI teams before the specified deadline during the Pointing Timeline Harmonization process.

The delivered PTR file names will have to contain the acronym of the DESIGNER instrument performing the delivery.

The delivery directory within JUICE_PREOPS is: <scenario_name>/POINTING.

Important

When delivering PTR files to the SOC the whole PTR file needs to be provided as per the latest harmonised version of the file. Updates are only expected in the PTR blocks that the instrument team is DESIGNER of.

SWI Pointing Table File (SPT)

The SWI Pointing Table file is used by the SWI team to indicate the planned SWI pointing. This pointing is translated into SWI Scanner SPICE CK Kernels (CK) by the SOC. SPT files are associated to a given PTR file.

The SOC does not deliver SPT files but rather the SWI Scanner SPICE CK Kernels (CK) that are generated based on the SPT files.

SPT files are delivered via merge request mechanism by SWI teams before the specified deadline during the Pointing Timeline Harmonization process.

The delivery directory within JUICE_PREOPS is: <scenario_name>/POINTING.

PTR SPICE CK Kernels (CK)

The generation of PTRs with OSVE/AGM also includes as a byproduct the generation of the corresponding SPICE CK kernel and also the MGA azimuth and elevation angles, and the Solar Arrays angles as “commanded” by the simulation of the AOCS sub-system of the S/C.

The SOC will deliver the SPICE CK kernels generated out of the delivered PTR files.

PTR CK files description and their naming convention are described in [PICD], the latest working version definition is available from PISICD_0201: S/C Pointing Timeline SOC Estimated CK.

PTR SPICE CK Delivery Mechanism

SOC Deliveries

Initial, or skeleton CK files, along with harmonised PTR CK files are delivered via direct merge by the SOC during the Pointing Timeline Harmonization process.

Regardless of this delivery, the SPICE CK kernels will also be included in the JUICE SPICE Kernel data set repository and also in the appropriate trajectory meta-kernel.

Note that the filename convention for SPICE CK files indicates that the entire filename is lower case.

Important

For SPICE CK deliveries only the resolved version of the original PTR file will be provided. This means that sxxpyy will not be part of the filename; only numbered versions e.g. s01p00

The delivery directory within JUICE_PREOPS is: <scenario_name>/POINTING.

PI Deliveries

PI teams do not deliver S/C CK files to the SOC but PTR files.

MAJIS Scanner SPICE CK Kernels (CK)

MAJIS team will deliver a number of MAJIS Scanner CK per observation in accordance with their latest observational strategy and based on the latest version of the applicable PTR and Spacecraft SPICE CK kernel.

The MAJIS Scanner CK files description and their naming convention are described in [PICD], the latest working version definition is available from PSICD_0400: MAJIS Planning CK scanner position per observation.

The SOC will then generate a single CK that will combine all the MAJIS deliveries as per the description and naming convention specified in [PICD], the latest working version definition is available from PSICD_0402: MAJIS Planning CK scanner position.

MAJIS Scanner CK Delivery Mechanism

SOC Deliveries

The MAJIS CKs generated by the SOC will be made available with a new release of the SPICE Kernel data set more concretely in the trajectory meta-kernel when agreed with the MAJIS team.

MAJIS Deliveries

CK files are delivered via merge request mechanism by the MAJIS teams before the specified deadline within the Pointing Timeline Harmonization process.

The delivery directory within JUICE_PREOPS is: <scenario_name>/TIMELINE/MAJIS/SCANNER.

SWI Scanner SPICE CK Kernels (CK)

Upon the reception of the SWI Pointing Table File (SPT) files the SOC will generate the corresponding SWI Scanner SPICE CK kernel that will provide SWI pointing information via the SPICE kernels.

The SWI Scanner CK files description and their naming convention are described in [PICD], the latest working version definition is available from PSICD_0502: SWI Planning CK scanner position.

SWI Scanner CK Delivery Mechanism

SOC Deliveries

The SWI CKs generated by the SOC will be made available with a new release of the SPICE Kernel data set more concretely in the trajectory meta-kernel when agreed with the SWI team.

PI Deliveries

SWI does not deliver S/C CK files to the SOC but SPT files.

Instrument Timeline File (ITL)

ITL files are used and exchanged by the SOC and PI teams during the Instrument Timeline Harmonisation (ITH).

In addition during the Observation Timeline Harmonisation (OTH) and Pointing Timeline Harmonisation (PTH) phases, the SOC will generate ITL files as support files to obtain approximated power and data volume resources resources and preliminary coverage for the observations. These ITLs are called Observation Timeline files (OTL) although ultimately they are ITL files.

In general ITL files can have two different flavors; they can either contain a timeline of observations or a timeline of actions (sequences, modelling actions, etc.):

An ITL can also contain a mix of both approaches.

“parameters”: {

“POWER_PROFILE”: “00:00:00 67432.0 [mW]”, “DATA_RATE_PROFILE”: “00:00:00 50.0 [bits/sec]”

}

or with

“data_rate_profile”: {

“unit”: “[Kbits/s]”, “values”: {

“00:00:00”: 23.0, “00:01:00”: 24.0

}

}

If the ITL is provided with respect to an event, the corresponding Event File (EVF) must be also available. Note that the COUNT provide the info about which event count the time is relative to.

The applicable event file for a detailed scenario is available at ENVIRONMENT/EVENTS/GEOMETRY/EVT_GEOPIPELINE_<scenario_id>.evf as indicated by the Top-level Event Definition file EVT_TOP_LEVEL_<scenario_id>_V<version>.evf.

Observation Timeline Files are a particular kind of ITL files that are only produced and delivered by the SOC in order to be used as support files to obtain approximated power and data volume resources resources and preliminary coverage for the observations.

They can be considered “skeleton” ITL files.

The only difference in between OTLs and the rest of ITL files is that the filename replaces ITL_ by OTL_.

ITL Generation

Typically the ITL files will be generated by PI team specific ad-hoc software.

To support ITL file generation especially for the SOC, ITLs can be automatically generated with observation timeline format from the existing Observation Plans (OPLs) with the juice-phs package.

ITL Delivery Mechanism

SOC Deliveries

Initial ITLs, or skeleton ITL files (OTLs) are delivered via direct merge by the SOC at the beginning of the Instrument Timeline Harmonisation process.

The delivery directory within JUICE_PREOPS are: <scenario_name>/TIMELINE/<ins>.

PI Deliveries

ITL files are delivered via merge request mechanism by the PI teams before the specified deadline within the Instrument Timeline Harmonisation process.

The delivery directory within JUICE_PREOPS is: <scenario_name>/TIMELINE/<ins>.

Event File (EVF)

EVF files are used during the Instrument Timeline Harmonisation (ITH) process and typically are provided by the SOC based on the relevant geometry and pointing events happening during the period (perijove, flyby, certain boundary crossing, etc.)

EVF Generation

EVF files are generated by the SOC using different internal tools.

Initially the events that have been used during the segmentation process will be made available for the detailed scenario. During the Pointing Timeline Harmonsation, the SOC will generate an event file from the PTR in such a way that observations can be scheduled with respect to the start or end of a pointing block.

A number of reference events will also be described, that could be used to schedule observations.

Additional events can be requested by the Instrument teams to the SOC at any time, the SOC will then deliver an event file with the appropriate events included.

EVF Delivery Mechanism

SOC Deliveries

EVF files are delivered via direct merge by the SOC whenever appropriate, typically at the beginning of the Observation Timeline Harmonisation as part of the starting kit and also after the Pointing Timeline Harmonisation when the PTR is frozen to include pointing events

The delivery directory within JUICE_PREOPS are: <scenario_name>/TIMELINE, or <scenario_name>/ENVIRONMENT/EVENTS and the corresponding sub-directory.

PI Deliveries

PI teams cannot deliver EVF files but they can request new event definitions to the SOC during any step of the planning process.