Spacecraft#

class Spacecraft(name: str, spice_id: int | str, tot_mass: ArrayWUnits = None, area: ArrayWUnits = None, ref_coeff: float = None, n_plate_model=None, thruster=None, instrument_list: list = [], body_fixed_frame_id=None, attitudeMode=None, fixedInertialAttitude=None, nadirPointingAxis=None)#

Bases: Body

Represents a spacecraft body.

Parameters:
namestr

The name of the spacecraft.

spice_idint | str

The NAIF ID code of the object. May be given as an integer ID or as a string.

tot_massArrayWUnits or SCBPolynomial, optional

The total (wet) mass of the spacecraft, passed to Body as its mass: an ArrayWUnits for a constant mass or an SCBPolynomial of time. Recommend expressed in units of kilograms. Defaults to None.

areaArrayWUnits, optional

The cross-sectional area of the spacecraft, used by CannonballSRP. Recommend expressed in units of \(m^2\). Defaults to None.

ref_coefffloat, optional

The reflectivity coefficient of the spacecraft, used by CannonballSRP. Defaults to None.

n_plate_modelnPlateModel, optional

The n-plate model that describes the shape and physical parameters of the spacecraft, used by nPlateSRP. Defaults to None.

thrusterActuator, optional

The thruster attached to the spacecraft. Defaults to None.

instrument_listlist[Instrument], optional

The Instrument objects attached to the spacecraft (cameras, antennas). Defaults to [].

body_fixed_frame_idint, optional

The SPICE ID of the spacecraft-fixed frame. Defaults to None.

attitudeModestr, optional

How the surface-force models (nPlateSRP, ThermalRadiation, AntennaRadiationPressure) orient the spacecraft-fixed frame. One of DynamicalUtils.ATTITUDE_MODES:

  • "CK": from the loaded C-kernel, whose frame ID is spice_id * 1000 (get_attitude()).

  • "inertialFixedAttitude": the constant rotation fixedInertialAttitude.

  • "nadirPointingSun": the \(-X\) axis points at the Sun and \(+Z\) along the heliocentric orbit normal, from the heliocentric position and velocity (nadirPointingSun()).

Any other value raises InvalidAttitudeModeError when one of those models first needs the attitude. Models that need none (gravity, CannonballSRP, an nPlateModel whose plates all sit in their own SPICE frames) accept the default. Defaults to None.

fixedInertialAttitudenumpy.ndarray, optional

The (3, 3) spacecraft-fixed to inertial rotation, required by attitudeMode="inertialFixedAttitude". Defaults to None.

nadirPointingAxisnumpy.ndarray, optional

The spacecraft-fixed axis meant to point at the Sun. It is stored and serialized only: the "nadirPointingSun" attitude always points \(-X\) at the Sun. Defaults to None.

Attributes:
area

The cross-sectional area of the spacecraft.

body_fixed_frame_id

The SPICE ID assigned to the spacecraft’s body-fixed frame.

instrument_list

The list of instruments attached to the spacecraft.

mass_profile

Stored constant or polynomial mass profile.

n_plate_model

The N-Plate model representing the spacecraft’s geometry.

name

The name of the spacecraft.

ref_coeff

The reflectivity coefficient of the spacecraft.

spice_id

The SPICE ID of the Body object.

thruster

Thruster actuator attached to this spacecraft, or None if not set.

Methods

add_instrument(instruments)

Adds an instrument or instruments to the spacecraft.

fit_mass_profile_from_data(t_array, m_array, ...)

Fits a polynomial to a mass time history and sets it as the new mass profile.

get_attitude(from_frame, epoch[, tol])

Computes the rotation from a given inertial frame to the spacecraft-fixed frame, from the C-kernel of frame ID spice_id * 1000.

get_dependent_spice_ids()

Collects the SPICE ID's of all attached frames and instruments into a dictionary.

get_mass(t)

Evaluates the time-varying mass profile at specified epochs.

get_state(epoch_0[, reference_frame, origin])

Retrieves the state of the body relative to a given origin in a specified reference frame.

inertial_to_body_DCM_nadirPointingSun(...)

Computes the Direction Cosine Matrix (DCM) that points the body frame's -X axis toward the Sun (nadir-to-sun), using inertial quantities.

mass([t])

Returns the mass of the body.

reset_mass_history()

Restore the mass the body was built with and forget fitted profiles.

set_mass_profile(poly, units)

Sets the mass profile of the body using a polynomial function and associated units.

See also

scarabaeus.nPlateModel

Geometric surface model for SRP computation.

scarabaeus.DynamicalUtils

Turns attitudeMode into the spacecraft-fixed to inertial rotation.

scarabaeus.Instrument

Generic instrument class (cameras, antennas).

scarabaeus.Body

Parent class providing SPICE ephemeris object management.

Notes

Spacecraft is the primary vehicle representation in Scarabaeus. It holds physical properties needed for force-model evaluation (mass, area, reflectivity), the optional nPlateModel for high-fidelity SRP modeling and the attitude the surface-force models orient it with. Instruments are registered via add_instrument().

A propagation with maneuvers integrates the mass and replaces tot_mass with a polynomial fit of the mass history, which mass() then evaluates; reset_mass_history() restores tot_mass.

add_instrument(instruments) → None#

Adds an instrument or instruments to the spacecraft.

Parameters:
instrumentslist of Instrument

The instruments to be attached to the spacecraft.

Returns:
None
fit_mass_profile_from_data(t_array: ndarray, m_array: ndarray, domain: tuple, units: Units) → None#

Fits a polynomial to a mass time history and sets it as the new mass profile.

Parameters:
t_arraynumpy.ndarray

Time values in seconds (ephemeris time).

m_arraynumpy.ndarray

Corresponding mass values.

degint

Degree of the polynomial.

domaintuple

Domain [t0, tf] for the polynomial conversion.

unitsArrayWUnits

Units to assign to the mass profile. If None, uses existing mass profile units.

Returns:
None
get_attitude(from_frame: Frame, epoch: EpochArray, tol: int = 0) → ndarray#

Computes the rotation from a given inertial frame to the spacecraft-fixed frame, from the C-kernel of frame ID spice_id * 1000.

Parameters:
from_frameFrame

The intertial reference frame for which the spacecraft-fixed frame will be transformed from.

epochEpochArray

The epoch at which the transformation will be performed. Given in ephemeris time (seconds past J2000).

tolint, optional

The time tolerance for retrieving attitude and angular velocity from the specified spacecraft clock time, given in sclock ticks. Defaults to 0.

Returns:
quatnumpy.ndarray

The (4,) SPICE quaternion (spice.m2q) of the rotation from from_frame to spacecraft-fixed coordinates.

Notes

The epoch argument is converted from ephemeris time in seconds to continuous encoded spacecraft clock ticks.

get_dependent_spice_ids()#

Collects the SPICE ID’s of all attached frames and instruments into a dictionary.

Parameters:
None
Returns:
idsdict

A dictionary containing the keys:

  • 'instruments' : list The SPICE ID’s of all attached Instrument objects.

  • 'plates' : list The SPICE ID’s of all C-frames for CK type panels defined in the nPlateModel if one has been assigned to the Spacecraft.

get_mass(t: EpochArray) → ArrayWUnits#

Evaluates the time-varying mass profile at specified epochs.

Parameters:
tEpochArray

Time(s) in ephemeris seconds (TDB).

Returns:
massArrayWUnits

Evaluated mass at each input epoch.

get_state(epoch_0, reference_frame: str = 'J2000', origin: str = 'EARTH') → ArrayWFrame#

Retrieves the state of the body relative to a given origin in a specified reference frame.

Parameters:
epoch_0EpochArray

The epoch times for which the state is to be computed.

reference_framestr

The reference frame in which the state is desired. Defaults to ‘J2000’.

originstr

The origin body relative to which the state is computed. Defaults to 'EARTH'.

Returns:
state_vectorArrayWFrame

The state vector of the body relative to the origin.

inertial_to_body_DCM_nadirPointingSun(origin_name, frame, sun2body_pos, current_state: dict, epoch, body)#

Computes the Direction Cosine Matrix (DCM) that points the body frame’s -X axis toward the Sun (nadir-to-sun), using inertial quantities.

Deprecated since version 2026.0.0: Use nadirPointingSun(), which returns the spacecraft-fixed to inertial DCM (the transpose of this one) and, on request, its position and velocity derivatives. This method now delegates to it.

Parameters:
origin_namestr

Name of the origin at which current_state is defined (e.g., ‘EARTH’, ‘SUN’).

frameFrame or str

Frame in which current_state is expressed (e.g., J2000).

sun2body_posArrayWUnits

Position of the body w.r.t. SUN (km).

current_statedict

State of the body w.r.t. the origin, keyed either by ('velocity', spice_id) or by 'velocity', with an array or ArrayWUnits value (and similarly for 'position' if ever needed).

epochfloat

Epoch (TDB seconds past J2000) at which the state is computed.

bodyCelestialBody or Spacecraft

The body whose state we are extracting from current_state (used for spice_id lookup).

Returns:
DCM_inertial_to_body(3,3) ndarray

DCM that rotates inertial vectors into the body-fixed frame realizing the nadir-to-sun pointing.

Raises:
DynamicalUtils.MissingVelocityError

If current_state holds no velocity for body (a KeyError).

mass(t: EpochArray | float | ndarray = None) → ArrayWUnits#

Returns the mass of the body. If the mass is time-varying, evaluates it at time t. If the mass is constant, returns the same value regardless of t.

Parameters:
tEpochArray, float, or np.ndarray, optional

Time(s) in ephemeris seconds (TDB) at which to evaluate the mass. Or None for constant mass.

Returns:
ArrayWUnits

Mass at time t or constant mass.

reset_mass_history() → None#

Restore the mass the body was built with and forget fitted profiles.

Every propagated leg appends the profile it fitted, and the next leg starts from the last one. Propagating the same mission again (a filter re-linearizing its reference, say) would otherwise start the first leg from the mass the previous run ended with, and get_mass() would return profiles from earlier runs that cover the same epochs.

The profile lists are cleared in place: force-model copies of this body share them by reference.

Returns:
None
set_mass_profile(poly: SCBPolynomial, units: Units) → None#

Sets the mass profile of the body using a polynomial function and associated units.

Parameters:
polySCBPolynomial

A polynomial object representing the mass profile.

unitsUnits

The units associated with the mass profile.

Returns:
None
property area: ArrayWUnits#

The cross-sectional area of the spacecraft. Expressed in units of square meters.

property body_fixed_frame_id: int#

The SPICE ID assigned to the spacecraft’s body-fixed frame.

property instrument_list: list#

The list of instruments attached to the spacecraft.

property mass_profile: ArrayWUnits | SCBPolynomial#

Stored constant or polynomial mass profile.

property n_plate_model: nPlateModel#

The N-Plate model representing the spacecraft’s geometry.

property name: str#

The name of the spacecraft.

property ref_coeff: float#

The reflectivity coefficient of the spacecraft.

property spice_id: int | str#

The SPICE ID of the Body object.

property thruster#

Thruster actuator attached to this spacecraft, or None if not set.