*********************** 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: ``___SP.`` 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 ``SP`` 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 ``SP`` 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 :ref:`60_procedures_and_tools: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 :ref:`60_procedures_and_tools:SOC->PI Deliveries` The delivery directory within ``JUICE_PREOPS`` is: ``/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 :ref:`60_procedures_and_tools:PI->SOC Deliveries` The delivery directory within ``JUICE_PREOPS`` is: ``/TIMELINE/``. 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 ``_/DEFINITIONS/OBSERVATIONS//GLOBAL`` directory. In addition, if the science segments are linked to certain observation, these observations will also be made available at: ``_/DEFINITIONS/OBSERVATIONS//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 ``_/DEFINITIONS/OBSERVATIONS//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: ``/DEFINITIONS/OBSERVATIONS//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: ``/DEFINITIONS/OBSERVATIONS//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: ``/DEFINITIONS/OBSERVATIONS//SCENARIO`` PI teams cannot deliver files in the ``GLOBAL`` directory. Only the numbered versions ``SP`` 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: ``>/DEFINITIONS/OBSERVATIONS/JAN/ODF_SCENARIO__.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 :ref:`60_procedures_and_tools: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__SP.ptx`` each delivery will be made along an update of the ``SXXPYY`` file. The delivery directory within ``JUICE_PREOPS`` is: ``/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: ``/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 :ref:`50_planning_files:SWI Scanner SPICE CK Kernels (CK)` by the SOC. SPT files are associated to a given PTR file. SOC Deliveries ~~~~~~~~~~~~~ The SOC does not deliver SPT files but rather the :ref:`50_planning_files:SWI Scanner SPICE CK Kernels (CK)` that are generated based on the SPT files. PI Deliveries ~~~~~~~~~~~~~ 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: ``/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: ``/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: ``/TIMELINE/MAJIS/SCANNER``. SWI Scanner SPICE CK Kernels (CK) ================================= Upon the reception of the :ref:`50_planning_files: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.): - The description and naming convention for Observation Timeline ITLs are described in [PICD]_, the latest working version definition is available from `PSICD_0105: Observation Timeline File - ITL for observations (OTL) `_. - The description and naming convention for Action/Commanding ITLs are described in [PICD]_, the latest working version definition is available from `PSICD_0208: Instrument Timeline File - ITL for modes/commanding (ITL) `_. An ITL can also contain a mix of both approaches. ITL Syntax and Description ~~~~~~~~~~~~~~~~~~~~~~~~~~ "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 } } Events in ITL files ~~~~~~~~~~~~~~~~~~~ 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. .. Note::In general it is preferable to use events with relative times instead of absolute times. During this planning exercise, it might not be relevant except maybe to have a better understanding of the timeline but when conducting planning activities where events can change due to trajectory or pointing updates, if the observations are scheduled with respect to events, the ITLs might not require an update. The applicable event file for a detailed scenario is available at ``ENVIRONMENT/EVENTS/GEOMETRY/EVT_GEOPIPELINE_.evf`` as indicated by the Top-level Event Definition file ``EVT_TOP_LEVEL__V.evf``. OTL Files ~~~~~~~~~ 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: ``/TIMELINE/``. 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: ``/TIMELINE/``. 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: ``/TIMELINE``, or ``/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.