# SpiceManager, Celestial Bodies, and SCB Constants#

Last revised 2026 MAY

Introduction#

This tutorial will explore the core infrastructure within Scarabaeus (SCB) for SPICE kernel interaction and planetary body representations. In addition, it will show how to interface with its constants library, which contains physical parameters and planetary constants.

Imports and Setup#

First we’ll import the necessary libraries, define units, and load in supplementary data, which for this tutorial is the general metakernel which contains kernels for planetary epehemerides and leapseconds for time conversions.

[1]:
import scarabaeus as scb
import supplementary as supp

from dataclasses import fields
import numpy as np

# load tutorial data
data = supp.load_data()

## define the units and frames we'll be using across the tutorial
km, AU, kg, sec, day = scb.Units.get_units(['km', 'AU', 'kg', 'sec', 'day'])

J2000, ECLIPJ2000 = scb.Frame('J2000'), scb.Frame('ECLIPJ2000')
IAU_EARTH, IAU_JUPITER = scb.Frame('IAU_EARTH'), scb.Frame('IAU_JUPITER')

# load kernels
scb.SpiceManager.clear_kernels()    # make sure kernel pool is empty
scb.SpiceManager.load_kernel_from_mkfile(data.mk.path)
SCB supplementary data out of date.
---------------------------------------------------------------------------
StdinNotImplementedError                  Traceback (most recent call last)
Cell In[1], line 8
      4 from dataclasses import fields
      5 import numpy as np
      6
      7 # load tutorial data
----> 8 data = supp.load_data()
      9
     10 ## define the units and frames we'll be using across the tutorial
     11 km, AU, kg, sec, day = scb.Units.get_units(['km', 'AU', 'kg', 'sec', 'day'])

File ~/scb_public/scarabaeus/docs/online_documentation/sphinx_files/_collections/tutorials/supplementary/supp_data.py:433, in load_data()
    431 waiting = True
    432 while waiting:
--> 433     response = input("\nDownload and generate missing files? (y/n): ")
    434     match response.strip().lower():
    435         case "y":

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/ipykernel/kernelbase.py:1514, in Kernel.raw_input(self, prompt)
   1512 if not self._allow_stdin:
   1513     msg = "raw_input was called, but this frontend does not support input requests."
-> 1514     raise StdinNotImplementedError(msg)
   1515 return self._input_request(
   1516     str(prompt),
   1517     self._get_shell_context_var(self._shell_parent_ident),
   1518     self.get_parent("shell"),
   1519     password=False,
   1520 )

StdinNotImplementedError: raw_input was called, but this frontend does not support input requests.

SpiceManager#

SpiceManager is Scarabaeus’ interface with the SPICE toolkit. It handles kernel management, reference frame rotations, and state vectors. We saw above how to use it to clear, load, and examine kernels in the kernel pool.

Reference Frame Transformations#

get_xfrm(from_frame, to_frame, et) returns the 3×3 rotation matrix that maps vectors expressed in from_frame into to_frame at epoch et. Frame names follow the SPICE convention ("J2000", "ECLIPJ2000", "IAU_EARTH", …).

[2]:
et = 140254384.184625   # seconds past J2000
print("ECLIPJ2000 to J2000 :")
print(scb.SpiceManager.get_xfrm(ECLIPJ2000.name, J2000.name, et))

print("\nECLIPJ2000 to IAU_EARTH :")
print(scb.SpiceManager.get_xfrm(ECLIPJ2000.name, IAU_EARTH.name, et))
ECLIPJ2000 to J2000 :
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[2], line 3
      1 et = 140254384.184625   # seconds past J2000
      2 print("ECLIPJ2000 to J2000 :")
----> 3 print(scb.SpiceManager.get_xfrm(ECLIPJ2000.name, J2000.name, et))
      4
      5 print("\nECLIPJ2000 to IAU_EARTH :")
      6 print(scb.SpiceManager.get_xfrm(ECLIPJ2000.name, IAU_EARTH.name, et))

NameError: name 'ECLIPJ2000' is not defined

Body State Queries#

For any body in the kernel pool, SpiceManager returns its position, velocity, or full state relative to an observer in a chosen reference frame.

It contains a few different methods that return different information depending on what you need:

  • get_pos(target, et, frame, observer) : 3-vector position (km)

  • get_vel(target, et, frame, observer) : 3-vector velocity (km/s)

  • get_state(target, et, frame, observer) : 6-vector [pos; vel]

  • get_lighttime(target, et, frame, observer): one-way light-time (s)

We can see all of these values by getting the state of the Earth with respect to the Sun in J2000:

[3]:
# Earth w.r.t. the Sun at the reference epoch
print(f"Position only:\n{scb.SpiceManager.get_pos('Earth', et, J2000.name, 'Sun')}\n")
print(f"Velocity only:\n{scb.SpiceManager.get_vel('Earth', et, J2000.name, 'Sun')}\n")
print(f"Full state vector:\n{scb.SpiceManager.get_state('Earth', et, J2000.name, 'Sun')}\n")
print(f"Light time:\n{scb.SpiceManager.get_lighttime('Earth', et, J2000.name, 'Sun')}\n")
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[3], line 2
      1 # Earth w.r.t. the Sun at the reference epoch
----> 2 print(f"Position only:\n{scb.SpiceManager.get_pos('Earth', et, J2000.name, 'Sun')}\n")
      3 print(f"Velocity only:\n{scb.SpiceManager.get_vel('Earth', et, J2000.name, 'Sun')}\n")
      4 print(f"Full state vector:\n{scb.SpiceManager.get_state('Earth', et, J2000.name, 'Sun')}\n")
      5 print(f"Light time:\n{scb.SpiceManager.get_lighttime('Earth', et, J2000.name, 'Sun')}\n")

NameError: name 'J2000' is not defined

CelestialBody#

A CelestialBody contains physical constants of a planet or natural satellite (mass, mean radius, gravitational parameter) with a SPICE identifier for ephemeris queries. There are two ways to create one.

From Constants#

This is the faster of the two. It pulls the necessary values from Scarabaeus’ constants library. We can also view all the properties of the body using disp_properties():

[4]:
# create from constants and display
jupiter_from_constants = scb.CelestialBody.from_constants('JUPITER')
jupiter_from_constants.disp_properties()
                           Jupiter
==============================================================
mass                     : 1.898124671078627e+27 kg
mean_radius              : 69911.0 km
gravitational parameter  : 126686534.92180079 mu
reference frame          : IAU_JUPITER
SPICE ID                 : 599
attached ground stations : []

Direct Construction#

We can also give values directly to the initialization of CelestialBody. As an example, we’ll create a planet with values half that of Jupiter. We can access the same constants library the from_constants() pulled from directly and divide those by two to pass to the constructor:

[5]:
# get planetary constants for Jupiter
jov_pc = scb.constants.JUPITER

# create a half sized Jupiter
half_jupiter = scb.CelestialBody(name        = 'HALF_JUPITER',
                                 mass        = jov_pc.mass / 2,
                                 mean_radius = jov_pc.mean_radius / 2,
                                 grav_param  = jov_pc.GM / 2,
                                 base_frame  = jov_pc.ref_name,
                                 spice_id    = 599000)  # give it a different ID than the actual Jupiter
half_jupiter.disp_properties()
                            HALF_JUPITER
===================================================================
mass                     : 9.490623355393134e+26 kg
mean_radius              : 34955.5 km
gravitational parameter  : 63343267.460900396 mu
reference frame          : IAU_JUPITER
SPICE ID                 : 599000
attached ground stations : []

All major and minor bodies contained within the constants library hold their information as a PCInfo object, which we then pulled values from directly. Depending on the kind of body, some of these parameters may or may not exist. For example, the Moon’s primary is Earth, but the Earth is defined without a primary (even though the Sun is technically its primary). Below are all of the parameters contained within a PCInfo data class:

[6]:
phobos = scb.constants.PHOBOS

print('All PCInfo fields for Phobos:')
for field in fields(phobos):
    print(f' - {field.name}: {getattr(phobos, field.name)}')
All PCInfo fields for Phobos:
 - name: Phobos
 - spice_name: PHOBOS
 - ref_name: IAU_PHOBOS
 - body_center_id: 401
 - barycenter_id: None
 - mass: 1.0619160161956238e+16 kg
 - GM: 0.0007087546066894452 mu
 - mean_radius: 11.4 km
 - equatorial_radius: None
 - GM_barycenter: None
 - primary_body: Mars

Querying Ephemerides#

If the body exists in the kernel pool, get_state returns its position and velocity at any epoch. Below we query all eight planets’ heliocentric orbits over two years and plot them.

[7]:
# 2 year time interval with weekly sample rate
epochs = scb.EpochArray.interval(start = '2001 JAN 01 12:00:00.000',
                                 end   = '2003 JAN 01 12:00:00.000',
                                 dt    = scb.ArrayWUnits(7, day),
                                 sys   = 'TDB')

# query heliocentric state for each planet
planets = ['MERCURY', 'VENUS', 'EARTH', 'MARS',
           'JUPITER', 'SATURN', 'URANUS', 'NEPTUNE']
planet_traj  = {}
for planet in planets:
    cb     = scb.CelestialBody.from_constants(planet)
    states = []
    print(f'Querying {planet}...')
    for epoch in epochs:
        state = cb.get_state(epoch_0 = epoch, reference_frame = 'J2000',
                             origin = 'SUN').quantity
        states.append(state[0:2].convert_to(AU).values)
    planet_traj[planet] = np.array(states)
    print(f'Retrieved all states across {epochs.duration(day)} interval')

supp.supp_plotting.plot_planets(planets, planet_traj, epochs)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[7], line 4
      1 # 2 year time interval with weekly sample rate
      2 epochs = scb.EpochArray.interval(start = '2001 JAN 01 12:00:00.000',
      3                                  end   = '2003 JAN 01 12:00:00.000',
----> 4                                  dt    = scb.ArrayWUnits(7, day),
      5                                  sys   = 'TDB')
      6
      7 # query heliocentric state for each planet

NameError: name 'day' is not defined