Tour configuration#

Generic setup#

from planetary_coverage import TourConfig

The TourConfig is a helper to prepare the SPICE configuration to perform a Trajectory calculation. It requires to choose a metakernel mk or/and a set of kernels, a spacecraft, an optional instrument, and a primary target.

Here is the default values implemented:

tour = TourConfig(
  mk='5.1 150lb',
  version='v400',
  spacecraft='JUICE',
  target='Ganymede',
)

tour

<TourConfig> Spacecraft: JUICE | Target: GANYMEDE | Metakernel: juice_crema_5_1_150lb.tm | SKD version: v400_20221021_001

Kernels directory#

Hint

If you need to override other PATH_VALUES variables in the metakernel at runtime, you will need to use a Metakernel object. More details can be found in this section.

If you use a metakernel containing a $KERNELS key in the KERNELS_TO_LOAD values (most ESA metakernels do), you can overwrite this placeholder at runtime by supplying a kernels_dir argument:

TourConfig(
  mk='5.1 150lb',
  spacecraft='JUICE',
  target='Ganymede',
  kernels_dir='path_to/my_kernels/',
)

Tip

If the the spacecraft have a space in its name, you need to replace it by a _ , for example for Europa Clipper you should create a KERNELS_EUROPA_CLIPPER environment variable.

However, to avoid to hard code your kernels directory (that is user specific), we recommend that you create environment variable with the following pattern KERNELS_XXXX, with XXXX being the name of the spacecraft you want to study.

This variable can be setup globally or in a .env text-file in your current working directly (or any of its direct parent). For example, a possible .env file could look like this:

#
# SPICE kernels location
#
KERNELS_JUICE=/data/ESA/JUICE/kernels
KERNELS_EUROPA_CLIPPER=../kernels/Clipper

We recommend to use, short and absolute path when it’s possible.

Tip

If you are in a Jupyter/IPython environment, you can use directly the magic function %load_ext:

%load_ext planetary_coverage

Note

If a .env file is found, it will override the global environment variables. In case of doubt, use the print_kernels_dir() function to check your kernels environment variables:

from planetary_coverage import print_kernels_dir

print_kernels_dir()

Dotenv file found:
- .env

Kernels ENV variables:
- KERNELS_JUICE         : /data/ESA/JUICE/kernels (.env)
- KERNELS_EUROPA_CLIPPER: ../kernels/Clipper (.env)

If you get a KernelsDirectoryNotFoundError, it means that you have not correctly defined your kernels directory.

Kernels not found#

When some kernels are not present locally, you will get a KernelNotFoundError.

First you need to check that your kernels directory is correctly setup (with a KERNELS_XXXX environment variable or with a kernels_dir argument).

Then, you can either, download manually the missing kernels (if you know where they are) or you can let the tool download them for you. To enable automatic kernels downloads you just have to add download_kernels=True argument and all the missing kernels will be downloaded in your kernels directory.

TourConfig(
  mk='5.1 150lb',
  spacecraft='JUICE',
  target='Ganymede',
  download_kernels=True,
)

The default remote location of the kernels archive is based on the metakernel header content if a remote is explicitly present with a http[s]/ftp link, it will be used by the tool. If not, you need to provide it manually:

TourConfig(
  mk='5.1 150lb',
  spacecraft='JUICE',
  target='Ganymede',
  download_kernels=True,
  remote_kernels='https://remote.location.tld/',
)

SKD version and MK identifier#

ESA metakernels have an optional SKD_VERSION arguments to precisely identify a kernel release and to ensure a better reproducibility of the results. By default, the latest version will be used (pull from the ESA archive if available), but you can provided any valid version or release id (SKD_VERSION) and the tool will download the correct version from ESA bitbucket archive.

TourConfig(
    mk='5.1 150lb',
    version='v400',
    spacecraft='JUICE',
    target='Ganymede',
)

<TourConfig> Spacecraft: JUICE | Target: GANYMEDE | Metakernel: juice_crema_5_1_150lb.tm | SKD version: v400_20221021_001

New in version 0.12.0

ESA metakernels may have a secondary optional MK_IDENTIFIER. You can use this value directly if you need to pin a given metakernel:

TourConfig(
    mk='juice_crema_5_1_150lb_v400_20221026_001',
    spacecraft='JUICE',
    target='Ganymede',
)

More details on ESA metakernels are available in a dedicated section.

SPICE pool content#

By default, the metakernel and any additional kernels will be loaded in the SPICE pool. The SPICE pool will be purged and reloaded automatically if the required kernels changed.

To illustrate that, we can see that the SPICE pool is now populated with our metakernel and all the kernel that is contain:

from planetary_coverage import SpicePool

SpicePool

<SpicePool> 57 kernels loaded:
 - /tmp/juice_crema_5_1_150lb-bsffjozi.tm
 - /kernels/JUICE/ck/juice_sc_sat_crema_5_1_150lb_default_20220826_20351005_f20160326_v01.bc
 - /kernels/JUICE/ck/juice_sc_sat_crema_5_1_150lb_comms_20310721_20351004_f20160326_v01.bc
...
 - /kernels/JUICE/dsk/juice_sc_sa+y_v03.bds
 - /kernels/JUICE/dsk/juice_sc_sa-y_v03.bds

Hint

The metakernel was loaded as a temporary file (here in /tmp/). This is an expected behavior. It allows the tool to rewrite the PATH_VALUES (a.k.a. $KERNELS) at runtime that were initially hard-coded in the original file.

New in version 1.0.0

The TourConfig will manage the kernels in the SPICE pool for you, to make sure that the SPICE computations are always performed on the requested set of kernels. If you want to use pure spiceypy calculation, we recommend that you add a load_kernels=True attribute to force the loading of the kernels into the SPICE pool (for performance reasons, the TourConfig object loads the kernels only if a SPICE computation is performed).

TourConfig(
  mk='5.1 150lb',
  spacecraft='JUICE',
  target='Ganymede',
  load_kernels=True,
)

You can also force the loading of the kernels on the TourConfig object itself:

tour.load_kernels()

This method could be very handy if you need to switch between different set of kernels. It is also available on Trajectory and MetaKernel objects as well:

traj.load_kernels()
mk.load_kernels()

New in version 0.12.0

If you need to extend the kernels list of TourConfig object, you can use the .add_kernel() method. You will get a new TourConfig object with the previous set of kernel, plus the new one(s):

new_tour = tour.add_kernel('custom_1.ck', 'custom_2.ck')

You can provide one or more kernels at once. This method is also available on Trajectory objects as well:

new_traj = traj.add_kernel('new.ck')

More details on the SpicePool can be found in the SPICE toolbox section.

Planetary coverage documentation

Tour configuration

Contents

Tour configuration#

Generic setup#

Kernels directory#

Kernels not found#

SKD version and MK identifier#

SPICE pool content#