spiceInterface#

Executive Summary#

The SPICE interface class gets time and planetary or spacecraft body information from the JPL ephemeris library

The module PDF Description contains further information on this module’s function, how to run it, as well as testing.

Message Connection Descriptions#

The following table lists all the module input and output messages. The module msg connection is set by the user from python. The msg type contains a link to the message structure definition, while the description provides information on what this message is used for.

Module I/O Messages#
Msg Variable Name	Msg Type	Description
spiceTimeOutMsg	SpiceTimeMsgPayload	spice time sampling output message
epochInMsg	EpochMsgPayload	(optional) input epoch message
planetStateOutMsgs	SpicePlanetStateMsgPayload	vector of planet state output messages
secondaryStateOutMsg	SpicePlanetStateMsgPayload	(optional) state output message for a secondary body attached to one of the planets in `planetStateOutMsgs`
scStateOutMsgs	SCStatesMsgPayload	vector of spacecraft state messages
attRefStateOutMsgs	AttRefMsgPayload	vector of spacecraft attitude reference state output messages
transRefStateOutMsgs	TransRefMsgPayload	vector of spacecraft translation reference state output messages

User Guide#

This module uses the JPL Spice software to determine the position and orientation of both a celestial body, or a spacecraft. The appropriate Spice kernel must be loaded up to provide the state information for the selected body names.

To setup a celestial body, use the module method addPlanetNames(vector<string>) in python. Multiple object names can be provided by providing a list of names. With each module update cycle, the corresponding celestial body states are provided in the vector of output messages planetStateOutMsgs[]. Note that the vector elements are in the order that the celestial body names were added.

To use this module to read in spacecraft states from a spice kernel, then the spacecraft Spice name is added using the method addSpacecraftNames(vector<string>). The module provides a vector out corresponding spacecraft state output messages in three different formats.

scStateOutMsgs[]: these are the SCStatesMsgPayload state output messages that the spacecraft module provides
attRefStateOutMsgs[]: these are the attitude reference messages AttRefMsgPayload. These are useful to only prescribe the spacecraft attitude motion.
transRefStateOutMsgs[]: these are the translational reference message TransRefMsgPayload. These are useful to only prescribe the translational motion and leave the attitude motion free.

Secondary Body#

A SecondaryBody can be attached to one of the celestial bodies in planetStateOutMsgs to model a small companion (for example, the secondary of a binary asteroid). Each module update writes a SpicePlanetStateMsgPayload on secondaryStateOutMsg whose PositionVector is the primary’s SPICE-derived position plus a configurable offset, and whose PlanetName is set to the secondary’s name (the primary’s planet message is not modified).

Configure a secondary body in python:

secondary = spiceInterface.SecondaryBody()
secondary.secondaryName = "companion"
secondary.positionOffset = [1000.0, 2000.0, -3000.0]  # m, in the inertial frame
secondary.orbitalPeriod = 11.92 * 3600.0              # s; 0 (default) keeps the offset static
spice.setOffsetBody("primaryName", secondary)

When a non-zero orbitalPeriod T is set, the secondary moves on a circle of radius \(|\boldsymbol{r}_{\text{offset}}|\) centered on the primary, at angular rate \(\omega = 2\pi/T\). The orbit plane has normal \(\boldsymbol{r}_{\text{offset}} \times (\boldsymbol{r}_{\text{offset}} \times \hat{Z})\), which keeps the plane tilted toward the equator (perpendicular to Z) rather than running through the poles. The secondary starts at positionOffset at \(t = 0\) and a quarter period later passes through a vector that lies in the equatorial (XY) plane. When the offset is parallel to Z the construction degenerates and the orbit plane normal is instead \(\boldsymbol{r}_{\text{offset}} \times (\boldsymbol{r}_{\text{offset}} \times \hat{X})\). With orbitalPeriod = 0 the offset is held constant.

To stop publishing secondaryStateOutMsg without discarding the configuration, call spice.passivateSecondary(). The stored SecondaryBody is preserved, and a subsequent setOffsetBody() call re-activates the output.

Limitations#

The secondary body model is a simple kinematic prescription, not a dynamics integration. Specifically:

Circular orbit only. The offset is rotated at a constant angular rate \(2\pi/T\) about the primary. There is no eccentricity, perturbation, or two-body integration; supplying an orbitalPeriod does not solve any equations of motion.
Orbit plane derived from the offset and J2000 Z. The plane normal is \(\boldsymbol{r}_{\text{offset}} \times (\boldsymbol{r}_{\text{offset}} \times \hat{Z})\) (or substitute \(\hat{X}\) for \(\hat{Z}\) when offset is parallel to Z); arbitrary user-specified orbital planes are not supported.
Single secondary per ``SpiceInterface`` instance. Only one body in planetStateOutMsgs can have a secondary attached at a time. A second binary system requires a second SpiceInterface instance.
Velocity is inherited, not orbital. secondaryStateOutMsg.VelocityVector is copied from the primary; it does not include the secondary’s \(\boldsymbol{\omega}\times\boldsymbol{r}\) contribution. Consumers that need a kinematically consistent velocity must compute it themselves.
Initial phase set by the offset vector. At \(t = 0\) the secondary is located at the configured positionOffset. To start at a different phase, rotate the offset vector before calling setPositionOffset.
Attitude (J20002Pfix) inherited from the primary. No body-frame orientation of the secondary is computed.

Class SpiceInterface#

class SpiceInterface : public SysModel#

spice interface class

Public Functions

SpiceInterface()#: This constructor initializes the variables that spice uses. Most of them are not intended to be changed, but a couple are user configurable.

~SpiceInterface()#: The only needed activity in the destructor is to delete the spice I/O buffer that was allocated in the constructor

void updateState(uint64_t currentSimNanos)#

This method is the interface point between the upper level simulation and the SPICE interface at runtime. It calls all of the necessary lower level methods.

Parameters:: currentSimNanos – The current clock time for the simulation
Returns:: void

int loadSpiceKernel(char *kernelName, const char *dataPath)#

This method loads a requested SPICE kernel into the system memory. It is its own method because we have to load several SPICE kernels in for our application. Note that they are stored in the SPICE library and are not held locally in this object.

Parameters:

kernelName – The name of the kernel we are loading
dataPath – The path to the data area on the filesystem

Returns:

int Zero for success one for failure

int unloadSpiceKernel(char *kernelName, const char *dataPath)#

This method unloads a requested SPICE kernel into the system memory. It is its own method because we have to load several SPICE kernels in for our application. Note that they are stored in the SPICE library and are not held locally in this object.

Parameters:

kernelName – The name of the kernel we are unloading
dataPath – The path to the data area on the filesystem

Returns:

int Zero for success one for failure

std::string getCurrentTimeString()#: class method

void reset(uint64_t currentSimNanos)#: Reset the module to original configuration values.

void initTimeData()#

This method is used to initialize the zero-time that will be used to calculate all system time values in the Update method. It also creates the output message for time data

Returns:: void

void computeGPSData()#

This method computes the GPS time data for the current elapsed time. It uses the total elapsed times at both the GPS epoch time and the current time to compute the GPS time (week, seconds, rollovers)

Returns:: void

void pullSpiceData(std::vector<SpicePlanetStateMsgPayload> *spiceData)#

This method gets the state of each spice item that has been added to the module and saves the information off into the array.

Returns:: void

void writeOutputMessages(uint64_t CurrentClock)#

This method takes the values computed in the model and outputs them. It packages up the internal variables into the output structure definitions and puts them out on the messaging system

Parameters:: CurrentClock – The current simulation time (used for time stamping)
Returns:: void

void clearKeeper()#: class method

void addPlanetNames(std::vector<std::string> planetNames)#: take a vector of planet name strings and create the vector of planet state output messages and the vector of planet state message payloads

void addSpacecraftNames(std::vector<std::string> spacecraftNames)#: take a vector of spacecraft name strings and create the vectors of spacecraft state output messages and the vector of spacecraft state message payloads

void setOffsetBody(const std::string &planetName, const SecondaryBody &offsetBody)#

Attach a secondary body to a primary celestial body in the planet list. The secondary’s state is published to secondaryStateOutMsg as the primary’s SPICE-derived state plus the secondary’s (optionally time-varying) offset.

Parameters:

name – Name of the primary celestial body in the planet list
offsetBody – The SecondaryBody to attach

void passivateSecondary()#: Stop publishing the secondary state output message. The stored SecondaryBody configuration is preserved, so a subsequent setOffsetBody() call re-activates it.

Public Members

Message<SpiceTimeMsgPayload> spiceTimeOutMsg#: spice time sampling output message

ReadFunctor<EpochMsgPayload> epochInMsg#: (optional) input epoch message

std::vector<Message<SpicePlanetStateMsgPayload>*> planetStateOutMsgs#: vector of planet state output messages

Message<SpicePlanetStateMsgPayload> secondaryStateOutMsg#: State output message for a secondary body.

std::vector<Message<SCStatesMsgPayload>*> scStateOutMsgs#: vector of spacecraft state output messages

std::vector<Message<AttRefMsgPayload>*> attRefStateOutMsgs#: vector of spacecraft attitude reference state output messages

std::vector<Message<TransRefMsgPayload>*> transRefStateOutMsgs#: vector of spacecraft translational reference state output messages

std::string SPICEDataPath#: — Path on file to SPICE data

std::string referenceBase#: — Base reference frame to use

std::string zeroBase#: — Base zero point to use for states

std::string timeOutPicture#: — Optional parameter used to extract time strings

bool SPICELoaded#: — Boolean indicating to reload spice

int charBufferSize#: — avert your eyes we’re getting SPICE

uint8_t *spiceBuffer#: — General buffer to pass down to spice

std::string UTCCalInit#: — UTC time string for init time

std::vector<std::string> planetNames = {}#: — Vector of the input planet names

std::vector<std::string> planetFrames#: — Optional vector of planet frame names. Default values are IAU_ + planet name

std::string planetWithSecondary = {}#: — Optional : planet in the list which will have a secondary body attached

SecondaryBody secondaryBody = {}#: — Optional : the secondary body

bool timeDataInit#: — Flag indicating whether time has been init

double J2000ETInit#: s Seconds elapsed since J2000 at init

double J2000Current#: s Current J2000 elapsed time

double julianDateCurrent#: s Current JulianDate

double GPSSeconds#: s Current GPS seconds

uint16_t GPSWeek#: — Current GPS week value

uint64_t GPSRollovers#: — Count on the number of GPS rollovers

BSKLogger bskLogger#: — BSK Logging

spiceInterface#

Executive Summary#

Message Connection Descriptions#

User Guide#

Secondary Body#

Limitations#

Class SpiceInterface#

This Page