Procedures and Tools

Usage of Python Notebooks

During the Detailed Scenario Activity, Jupyter Notebooks will be used to run different tools, interact, communicate, and to display different information during the planning meetings. There will be at least one Python Notebook for each of the steps of the detailed scenario process: OTH, PTH, and ITH.

Jupyter Notebooks JSON static files that can be interpreted by Jupyter into a web application for creating and sharing computational documents. They offer a simple, streamlined, document-centric experience and have been identified as the optimal interface for most of the Detailed Scenario Planning activities and are intended to slowly replace MAPPS functionalities.

A Python 3 installation is assumed. To install Jupyter Lab/Notebeooks:

During the Detailed Scenario exercise we will use several Jupyter Notebooks that will be made available in the JUICE_PREOPS repository, more concretely under the NOTEBOOKS directory. The resulting HTML from the execution of these notebooks will also be made available.

During the process, different Python packages will be used that are described in the 30_procedures_and_tools:Operational Tools section.

More information on the usage of JUICE SOC Python Notebooks is available at the JUICE SOC Toolkit Help.

SPICE Kernels Setup

Having SPICE setup is fundamental to carry out the detailed scenario exercise.

First of all, you need to ensure that you have SPICE installed in your computer. We recommend to use SpiceyPy the Python wrapper of SPICE. You can install it as any other Python library using the Python package index; pip install spiceypy. This will install CSPICE with a Python wrapper. Alternative methods available from the SpiceyPy GitHub repository.

If you wish to install SPICE for other languages follow the instructions under the NAIF Toolkit page.

Warning

If you have the SPICE Toolkit already installed, make sure it is version N67 or a later one.

The SPICE Kernels can be setup in a plethora of ways. Here we provide the one that is recommended by the JUICE SOC and by the ESA SPICE Service.

  1. Clone the SPICE Kernels: Clone the JUICE SPICE kernel data set from BitBucket. Clone it from the terminal with:

    git clone --depth 1 https://s2e2.cosmos.esa.int/bitbucket/scm/spice_kernels/juice.git

    Please be aware that due to the large history of the repository and the large size of some binary kernels, timeout errors may occur if the --depth option is not used for performing a shallow clone.

    ALTERNATIVELY download the kernels from the ESA SPICE FTP, you should do so by downloading the kernels listed in any Meta-kernel. Good luck with that.

  2. Update the meta-kernel for local usage: In order to use the kernels with the Meta-kernels in SPICE outside of the Meta-kernel directory of the Git repository the user needs to modify the following PATH_VALUE variable of the meta-kernel from:

    PATH_VALUES       = ( '..' )

    to:

    PATH_VALUES = ( '<Absolute Path to 'kernels' directory>' )

    The meta-kernel can be found in the directory juice/kernels/mk/

    It is recommended for users to make a local copy of the meta-kernel and modify the value of the PATH_VALUES keyword to point to the actual location of the JUICE SPICE data set’s data directory on their system. Replacing / with \ and converting line terminators to the format native to the user’s system may also be required if this meta-kernel is to be used on a non-UNIX workstation.

    It is highly recommended to automatise this updates for every time the kernels need to be udpated by using the available Git Hooks

  3. Install SKD Git Hooks skd_post_merge is a set of Git Hooks with the responsibility of creating or updating the local Meta-Kernels of a given SPICE Kernel Dataset (SKD) everytime that the local repository of the SKD is updated. This update usually is triggered by a git pull, git merge or a git checkout.

    Install them with the terminal from the SPICE juice kernels directory with:

    misc/git_hooks/skd_post_merge/install_hook_linux_or_mac.sh

    You can also update the meta-kernel anytime by running the following script:

    misc/git_hooks/skd_post_merge/update_local_mks.sh

  1. Test the kernels: Download the BRIEF utility from NAIF utilites page Put it under your system PATH or directly in the directory juice/kernels/mk/. Run it from the command line with ./brief <name of the metakernel>, you should see something like:

    brief juice_crema_5_0_local.tm

BRIEF -- Version 4.1.0, September 17, 2021 -- Toolkit Version N0067

Summary for: /Users/marc.costa/spice/juice/kernels/spk/juice_sci_v02.bsp
Bodies: JUICE_JUP_HALO_RING (-28941)*
        JUICE_JUP_MAIN_RING (-28942)*
        JUICE_JUP_AMA_GOS_RING (-28943)*
        JUICE_JUP_THE_GOS_RING (-28944)*
        JUICE_JUP_THE_RING_EXR (-28945)*
        JUICE_IO_PLASMA_TORUS (-28968)*
        JUICE_EUROPA_PLASMA_TORUS (-28988)*
        Start of Interval (ET)              End of Interval (ET)
        -----------------------------       -----------------------------
        1950 JAN 01 00:00:00.000            2050 JAN 01 00:00:00.000
(...)

Note

A very practical alternative to the SPICE Kernel setup is to use the planetary-coverage Python package to obtain and manage the SPICE Kernels. Full instructions available in its Documentation.

Operational Tools

During the Detailed Scenario process, a number of tools are provided by the SOC in order to conduct the exercise, most of these tools are only available in Linux and Mac.

The SHT Timeline Tool, OSVE with Python Notebooks, the Pointing Tool (and PTWrapper), Cosmographia and optionally Cesium Viewer are the core tools to be used. However MAPPS remains as an operational backup. MAPPS is available as Linux, Mac, and Windows operational systems.

SHT Timeline Tool

The Timeline Tool, also known as Segment Harmonization Tool (SHT) is a web-based tool supporting the collaborative and assisted creation of the science segmentation of a JUICE trajectory.

More information on the Timeline Tool is available at the JUICE SOC Toolkit Help.

The Timeline Tool has been adapted in order to be able to support the Observation Timeline Harmonisation process of the detailed scenario exercise.

Observations as Segments

To accommodate this process, “observation” segments have been added to the Core configuration of the Timeline Tool; one per instrument: JANUS, MAJIS, PEP, etc. In addition a number of segment definitions placeholders have been defined to fit the “observation” segments or constructs required for the process, i.e. <INSTRUMENT>_OBSERVATION, <INSTRUMENT>_DESIGNER_OBSERVATION, <INSTRUMENT>_PRIME_OBSERVATION, and <INSTRUMENT>RIDER_OBSERVATION

These “observation” segments belong to their instrument group and need to be checked as Prime Segment in order to be usable in the Timeline Tool.

Skeleton PTR Generation

In addition, the functionality to generate a baseline PTR for a detailed scenario has been added. By using the “Generate Skeleton PTR” function the Timeline Tool will use the segment PTR blocks (defined by the SOC or provided by the DESIGNER team) introduced in the updated segment definitions from the plan in use.

SHT API

The SHT/Timeline Tool Rest API allows you to retrieve most of the information provided by SHT in order to generate your own graphics or analysis derived from that information.

You can retrieve all the Segmentation Plans available from the Timeline tool in JSON format using with the following REST API query:

https://juicesoc.esac.esa.int/rest_api/trajectory/crema_5_1_150lb_23_1/plan

And once you identify the plan:

{
    "trajectory": "CREMA_5_1_150lb_23_1",
    "name": "S007_PJ12_S01P00",
    "created": "2023-10-04T00:07:50.050527Z",
    "mnemonic": "S007_PJ12_S01P00",
    "id": 219,
    "author": "mcosta",
    "description": "",
    "is_public": true,
    "refine_log": "",
    "ptr_file": "/rest_api/file/trajectory%23CREMA_5_1_150lb_23_1.ptx/"
}

you can retrieve it with its id:

https://juicesoc.esac.esa.int/rest_api/plan/219/

OSVE

The Operations, Simulation & Validation Engine (OSVE) is a Python package that uses the SOC core libraries; the Experiment Planning System (EPS) and the Attitude Generator Module (AGM) and is used to run a scenario simulation to generate the relevant outputs for the detailed scenario.

OSVE is considered to be the main tool used during the Instrument Timeline Harmonisation process.

OSVE requires Python and is available via PyPi and could be installed with the python package manager pip:

python -m pip install osve

OSVE is also available from the GitLab repository. OSVE detailed documentation is available here. The usage of OSVE will be illustrated with the ORB17 Python Notebooks.

Pointing Tool

The JUICE Pointing Design Tool or JUICE Pointing Tool (PT) is a web-based tool supporting the assisted creation of pointing requests for the JUICE planning activities. The PT uses AGM and EPS through OSVE on the backend.

The Pointing Tool is recommended to start the design of the PTR, online, during the Pointing Timeline Harmonisation process. However the Cosmographia Plugin (see below) is recommended if more details of the underlying geometry are required.

The PT also has an API that can be used as illustrated in the esa-ptr documentation.

More information on the Pointing Tool is available at the JUICE SOC Toolkit Help.

Pointing Tool Wrapper

The Pointing Tool Wrapper is a local tool supporting the assisted creation of pointing requests for the JUICE planning activities. It is basically a command-line offline version of the Pointing Tool and allows to simulate a Pointing Timeline Request (PTR) and to generate the corresponding SPICE CK, resolved PTR, available power, and quaternions dump file.

The PTWrapper is recommended to design PTRs offline during the Pointing Timeline Harmonisation process.

PTwrapper is based on OSVE and mainly provides a shortcut to use the required functionalities and setup limited to the simulation of PTRs. It also includes additional features such as advanced log to support the Pointing Design process, and also includes the Observation Compatibility checks specified at Observation Compatibilities.

PTWrapper requires Python and is available on PyPi and could be installed with the python package manager pip:

python -m pip install ptwrapper

So far, only Linux and Mac versions are available. More information is available at is also available from the GitLab repository. Detailed documentation still has to be generated.

SPICE-Enhanced Cosmographia

SPICE-Enhanced Cosmographia is a visualization program rendering the solar system and its bodies in 3D to create a freely navigable map of the solar system. The program allows manipulation of time and camera (observer) position. It can use SPICE data to visualize trajectory, orientation, and sensors flown on and observations taken by interplanetary spacecraft, to support scientific or engineering analysis, and perhaps even public outreach.

Although Cosmographia is not considered to be a JUICE SOC operational tool, it is still very adept to visualize the detailed scenario geometry and S/C attitude especially to support the pointing design during the PTH process.

More information and instructions on how to install Cosmographia are provided at the JUICE SOC Toolkit Help.

JUICE Cosmographia Plugin

When using Cosmographia for JUICE it is extremely recommended to use the JUICE SOC Cosmographia plugin given that it facilitates loading the JUICE Cosmographia configuration files, SPICE meta-kernel and facilitates the loading of individual SPICE CK files to visualize the attitude of a given S/C CK generated from a PTR.

Most important of all the Cosmographia plug-in incorporates OSVE and allows to simulate the PTR also providing a very handy timeline and viewpoint selector.

The Cosmpgraphia Plugin is available at the JUICE SOC Cosmos page

More information and instructions on how to install and use the JUICE SOC Cosmographia plugin are provided at the JUICE SOC Toolkit Help.

ESA PTR

esa-ptr is a Python package that implements an object oriented approach to help the creation and parsing of PTR files for the user, as well as an interface to check JUICE PTR validity with AGM.

Detailed documentation can be found here.

This package is available on PyPI and could be installed with the python package manager pip:

python -m pip install esa-ptr

JUICE PHS

JUICE PHS is a Python package to support the JUICE Science Operations Payload Planning processes. Amongst other functionalities, the package facilitates the generation of EPS files (ITLs, EVFs), along with other planning files.

JUICE PHS is available from the JUICE GitLab sever.

The usage of JUICE PHS will be illustrated with the PJ12 Python Notebooks <PJ12 Python Notebooks.

Cesium Viewer

The JUICE Cesium Viewer is a web based tool for attitude and coverage visualization to support the detailed planning process by providing attitude and observation coverage in 3D and 2D space by taking advantage of the Cesium Platform, the open platform for software applications deigned for 3D geospatial data.

The Cesium Viewer allows to explore the target of the detailed scenario and to load a scene that contains a JUICE model and its ephemeris (via SPICE Kernels) in order to be able to visualize a given trajectory and attitude of the spacecraft. In addition there is the possibility to load observation GeoJSON files that correspond to the geometry of the footprints of a given instrument timeline.

During the detailed scenario planning process the Cesium Viewer will be used as a visualization tool for the S/C attitude and for preliminary coverage analysis. If deemed necessary, Cesium Viewer data will be made available for each iteration of the planning process.

More information on the Cesium Viewer is available at the JUICE SOC Toolkit Help.

Planetary Coverage Package

The planetary-coverage package is a python toolbox to perform surface coverage analysis based on SPICE orbital trajectory calculations.

planetary-coverage is available from the JUICE GitLab sever. Detailed documentation can be found here

The usage of the Planetary Coverage Package will be illustrated with the PJ12 Python Notebooks.

MAPPS

Note

MAPPS is used as an operational backup to OSVE for the detailed scenarios.

The Mission Analysis and Payload Planning System (MAPPS) software is a user local (offline) software tool that supports the science operations planning of the planetary missions at ESAC. MAPPS for JUICE has the following main functionalities:

  • Scientific Payload Simulator

  • Graphical Timeline

  • Datapack Generation

  • 2D surface maps

  • Operational products generator

The core of MAPPS consists of EPS and AGM.

MAPPS has been the main operational tool during during the past Callisto 21C3 and Europa 7E1 flyby exercises and in fact the structure and organisation of the JUICE_PREOPS is a reflection of this given that has been structured around the way MAPPS is configured. Nevertheless MAPPS main functionalities are being optimised and made more versatile for the detailed scenario exercise by making use of Python Notebooks whils using MAPPS’s core functionalities (AGM and EPS) via the OSVE Package.

Instructions on how to setup MAPPS are provided in Confluence.

Procedures

This section provides the description of a number of procedures that will be exercised during the Detailed Scenario Activities. The procedures are linked from the relevant section of the Detailed Scenario Process.

The procedures provided hereunder are chronologically ordered with respect to when they are first intended to be used in the Detailed Scenario process.

PI->SOC Deliveries

PI to SOC deliveries are done via Git Merge Requests (MRs) to the JUICE_PREOPS repository scenario branch i.e.:S007_PJ12 from the PI’s instrument team branch i.e.:S007_PJ12_<ins>. The MRs are reviewed by the SOC and merged into the scenario branch (or rejected). MRs can be done in multiple ways, more information is available here Gitlab MRs.

The first step is to consolidate the updates in your local machine and push them to the GitLab server. You can follow the steps below:

  • Ensure you are at the instrument branch

    • ~/JUICE_PREOPS$ git checkout S008_ORB17_JANUS

  • In order to avoid a possible conflicts with the new work done by other colleagues in your branch, use fetch to get the latest updates:

    • ~/JUICE_PREOPS$ git fetch

  • Include the latest updates in your branch with pull

    • ~/JUICE_PREOPS$ git pull

  • Use your favorite editor to update or create a new APL version. For example

    • ~/JUICE_PREOPS$/PLANNING/SCENARIOS/ORB17/TIMELINE/JANUS$ cp ITL_JAN_S007_01_S00P01.json ITL_JAN_S007_01_S00P01.json

  • Once you are happy with the changes, add and commit the file (i.e. apply the changes in your local copy of the repository) and then do a push to the repository in the remote server. When you commit the file add a message that summarises the changes in the files. For example: * ~/JUICE_PREOPS$ git add -- ITL_JAN_S007_01_S00P01.json * ~/JUICE_PREOPS$ git commit -m "Created new version of the ITL" * ~/JUICE_PREOPS$ git push

The next step is to do the actual Merge Request from the GitLab server page. Follow the steps below:

  • In Gitlab your can select your branch and navigate into the Gitlab folders to visualize the files you committed.

  • From Gitlab Gitlab you can create a Merge Request available from the left column. Then click on New merge request. from your instrument branch (i.e. ORB17_JANUS) to the main branch (i.e. ORB17).

  • Select the instrument branch as Source branch and the main branch as Target branch.

  • Then click on Compare branches and continue.

  • You can include the Title of your merge request and brief description with the content of your new file added. You can also assign a person from the SOC to review your merge.

  • Finally, you create the Merge Request.

Please note that some applications allow to integrate Merge Requests connecting to GitLab.

The MR must be performed before the indicated deadline which will be communicated by the SOC.

The MR is reviewed by the SOC and merged into the scenario branch (or rejected) in preparation for the upcoming Detailed Scenario Process meeting.

SOC->PI Deliveries

Deliveries from the SOC will be performed via Git Push from the main branch in the JUICE_PREOPS (i.e. S008_ORB17) repository. Due to that the PI teams need to actively carry out a merge from the main branch to the instrument branch whenever the SOC indicates that a delivery happened. To do so follow the steps below:

  • Ensure you are at the instrument branch

    • ~/JUICE_PREOPS$ git checkout PCW3_JANUS

  • In order to avoid a possible conflicts with the new work done by other colleagues in your branch, use fetch to get the latest updates:

    • ~/JUICE_PREOPS$ git fetch

  • Include the latest updates in your branch with pull

    • ~/JUICE_PREOPS$ git pull

  • Check if you have any local changes with a status

    • ~/JUICE_PREOPS$ git status

    • If you see Changes to be committed: then you changed files.

  • If you have local changes, add and commit the file (i.e. apply the changes in your local copy of the repository) and then do a push to the repository in the remote server. When you commit the file add a message that summarises the changes in the files. For example:

    • ~/JUICE_PREOPS$ git add -- ITL_JAN_S008_ORB17_S00P01.json

    • ~/JUICE_PREOPS$ git commit -m "Created new version of the ITL"

    • ~/JUICE_PREOPS$ git push

  • Merge the main branch to your instrument branch locally:

    • ~/JUICE_PREOPS$ git merge PCW3

In case there are conflicts, solve them locally. There should be no conflicts unless you modified a file that you are not supposed to modify, if you cannot resolve the conflicts contact the JUICE SOC.

Important

The Push to the scenario branch will be performed before the indicated deadline and will be communicated by the SOC via email. Please note that the SOC delivery must be integrated before starting to work on the subsequent (PI->SOC) delivery.

SOC to PI deliveries are done via Git Push to the scenario branch i.e.:S007_PJ12 by the SOC. The instrument teams are then responsible for pulling the changes from the scenario branch to their instrument team branch and resolving any conflicts. The SOC will not resolve conflicts in the instrument team branches.

OPL Generation with the Timeline Tool

OPL file generation can be assisted by the SHT Timeline Tool CSV export functionality.

In order to do so, the first step is to load the segmentation plan that corresponds to the detailed scenario. The segmentation plan reference will be provided by the SOC at the start of the Detailed Scenario process as part of the Starting Kit.

The PRIME timeline of the plan contains the current prime observation schedule. For the first iteration, these still correspond to the segments coming from the segmentation. For sub-sequent iterations, there will be a timeline with the observation plan that each instrument team has provided in the previous delivery.

After doing so it is recommended to clone a segment to update it afterwards. To clone a segment right click on it and choose the option “Clone in…” select then the timeline that corresponds to your instrument. When you clone a segment in a different timeline its start and end times are copied and you can re-define the segment as an observation instantiation.

The next step is to update the segment. Right click on the new segment and choose “Update item”. Edit the fields as follows:

  • Name: Provide the Observation Name. Note that this name must correspond to an already existing Observation on the observation database or on the observation definition files in the JUICE_PREOPS repository.

  • Definition: Assign to the “segment” the definition that corresponds to your instrument <INSTRUMENT>(_PRIME/DESIGNER/RIDER)_OBSERVATION. If the observation will be Prime (Defines Pointing) then choose the Prime Observation. For example for a JANUS Prime Observation choose JANUS_PRIME_OBSERVATION.

Finally click on “Update”. Now you can also move the observation around the timeline, crop it, re-define the start time, etc. Perform as many operations as required and create as many observations as required.

Example on how to generate an observation from a segment in the SHT Timeline Tool.

Example on how to generate an observation from a segment in the SHT Timeline Tool.

Please note that you can also create an observation by double-clicking on the timeline. When doing so please ensure that you select the appropriate “Timeline” in the segment creation window.

Once your observation plan file is ready, export it with the Timeline tool by using the “CSV Export” option. When doing so make sure you only select your instrument timeline and select the “All” tab to export the timeline of your instrument, e.g. JANUS timeline (the one you used to create/edit your observations). You will obtain a file similar to:

JANUS_PRIME_OBSERVATION,2032-09-23T02:53:51.000Z,2032-09-23T14:49:03.000Z,JAN_VERTICAL_SCAN,JANUS
JANUS_PRIME_OBSERVATION,2032-09-24T02:48:51.000Z,2032-09-24T08:00:00.000Z,JAN_FEATURE_TRACK,JANUS
JANUS_OBSERVATION,2032-09-24T08:00:00.000Z,2032-09-24T11:58:51.000Z,JAN_RIDER,JANUS
JANUS_PRIME_OBSERVATION,2032-09-24T16:00:00.000Z,2032-09-24T16:31:09.000Z,JAN_70MIN_DISK_SCAN,JANUS

Rename the file from the default name, which will be similar to export_S007_PJ12_S00P00_2023-06-01T11_01_11.csv, applying the appropriate filename convention, e.g. OPL_JAN_S007_01_S01P01.csv.

This observation plan that you have generated is not persistent in the Timeline Tool, if you want to recover it you only need to load the appropriate plan and then import the CSV with “CVS Import”. The plan will be persistent once you have delivered the file and the SOC has integrated it.

For more information on the usage of the SHT Timeline Tool refer to its User Manual in the JUICE SOC Toolkit Documentation.

PTR Generation Guidelines and Rules

Instrument teams need to design the PTR blocks for which they have been assigned a DESIGNER status. A description of what a PTR is provided in 50_planning_files:PTR Description.

PTR block design can be performed with the assistance of the following tools:

  • Pointing Tool: Recommended by the SOC, the visualization might not provide all needed functionalities.

  • Pointing Tool Wrapper: Recommended when working offline. Needs to be complemented by a visualization tool.

  • ESA PTR: Recommended for programmatic generation of PTRs.

  • OSVE: Not recommended yet usable.

More information and documentation on these tools are provided in the sections linked above.

The usage of the JUICE Cosmographia Plugin to assist the PTR visualization is extremely recommended.

Some indications and general recommendations are provided hereunder:

  • While designing PTRs, and during the PTH process, intermediate PTRs that are delivered to the SOC can have errors or constraint violations in order to facilitate the process. These PTR issues can be discussed with the SOC. Ultimately, the final PTRs delivered to the SOC in the last iteration must be error free.

  • PTRs should only contain updates for the observation blocks for which the Instrument Team is DESIGNER.

  • The PTR segment block must comply with the segment start and end times agreed as per the DESIGNER observation plan. Some flexibility is expected but needs to be discussed during the OTH and PTH processes with all parties involved.

Some applicable rules with respect to the slews:

  • Input PTR vs Resolved PTR: A PTR block can have an open start or end time to optimize the slew before/after the block. If the input PTR has “open” blocks AGM (Pointing Tool, OSVE, MAPPS, etc.) will calculate the slew and generate the resolved PTR that will include the optimal start and/or end time.

  • Maintenance blocks segments: OPNAV_CAL, J_FD_WOL, J_FD_TCM, and DL_ slews are considered in their duration and therefore no conflict shall be accounted for during the PTH process.

  • Absorption of the unexpected slew time needs to be agreed in between consecutive DESIGNER Instrument Teams observations. Ideally these agreements need to happen during the OTH process especially concerning the phase angle (secondary axis resolution) of a set of blocks. In case there is no agreement between consecutive observations of different primes, each observation will be forced to slew back to the baseline default pointing.

  • The checks that must be observed during the Pointing Timeline Harmonisation are described in Detailed Scenario Constraints