CelestialBody#

class CelestialBody(name: str, mass: ArrayWUnits = None, mean_radius: ArrayWUnits = None, grav_param: ArrayWUnits = None, base_frame: Frame | str = None, spice_id: int | str = None, barycenter_id: int | str = None, barycenter_GM: ArrayWUnits = None, gs_list: list = [])#

Bases: Body

Defines an astronomical body such as a planet, moon, asteroid, or comet.

Parameters:
namestr

The written name of the CelestialBody.

massArrayWUnits, optional

The mass of the CelestialBody, in any mass units. Recommend expressed in units of kilograms. Derived from grav_param when omitted. Defaults to None.

mean_radiusArrayWUnits, optional

The mean radius of the CelestialBody, in kilometers. Defaults to None.

grav_paramArrayWUnits, optional

The gravitational parameter of the CelestialBody, in units of \(\frac{km^3}{s^2}\). Derived from mass when omitted. Defaults to None.

base_frameFrame or str, optional

The body-centered, body-fixed reference frame attached to the CelestialBody, as a Frame or a frame name. Defaults to None.

spice_idint or str, optional

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

barycenter_idint, optional

The NAID ID code of the object’s barycenter_id. Defaults to None.

barycenter_GMArrayWUnits, optional

The gravitational parameter of the body’s barycenter if it has one. Defaults to None.

gs_listlist, optional

A list containing all of the ground stations on the surface of the CelestialBody. Defaults to [].

Attributes:
barycenter_GM

The gravitational parameter of the body’s system barycenter, if defined.

barycenter_id

The SPICE ID of the object’s barycenter.

base_frame

The reference frame attached to the CelestialBody.

base_frame_name

Name of the reference frame attached to the CelestialBody.

grav_param

The gravitational parameter of the CelestialBody given, by convention, in units of \(\frac{km^3}{s^2}\), if defined.

gs_list

All GroundStation objects attached to the surface of the CelestialBody.

mass_profile

Stored constant or polynomial mass profile.

mean_radius

The mean radius of the CelestialBody, if defined.

name

The name of the Body object.

spice_id

The SPICE ID of the Body object.

Methods

barycenter()

Stripped version of the

disp_properties()

Displays all properties of the CelestialBody object in a readable format.

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.

from_constants(cb_names)

Create a CelestialBody from a given name using its respective values as defined in constants.

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.

mass([t])

Returns the mass of the body.

planets()

Create each of the eight planets as defined in constants.

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.constants

Scarabaeus’ constants library, including planetary constants.

scarabaeus.Frame

Scarabaeus’ representation of reference frames.

Notes

The gravitational parameter \(\mu\) is defined as

\[\mu = GM\]

where \(G = 6.674\times10^{-20}\ \mathrm{km}^3\,\mathrm{kg}^{-1}\,\mathrm{s}^{-2}\) is the universal gravitational constant and \(M\) is the body mass. The circular orbital velocity at distance \(r\) and surface escape velocity are

\[v_{circ} = \sqrt{\frac{\mu}{r}}, \qquad v_{esc} = \sqrt{\frac{2\mu}{R_{mean}}}\]

Use grav_param (\(\mu = GM\)) rather than mass for orbital computations to avoid rounding errors from \(G\).

Only one of mass and grav_param is needed: the missing one is derived through \(\mu = GM\) with Constants.G. When both are given, both are kept as supplied. When neither is given, both stay None, which is fine for a body used only as an origin or an ephemeris target but not for one that exerts gravity.

Examples

Create a CelestialBody object with numerical values that are half that of Jupiter.

>>> import scarabaeus as scb
>>> jov_constants = scb.constants.JUPITER
>>> half_jupiter = scb.CelestialBody(
...     name        = "HALF JUPITER",
...     mass        = jov_constants.mass / 2,
...     mean_radius = jov_constants.mean_radius / 2,
...     grav_param  = jov_constants.GM / 2,
...     base_frame  = jov_constants.ref_frame,
...     spice_id    = 50000,
...     gs_list     = []
... )

Create a body from its gravitational parameter alone; the mass is derived.

>>> half_jupiter = scb.CelestialBody(
...     name       = "HALF JUPITER",
...     grav_param = jov_constants.GM / 2,
...     spice_id   = 50000,
... )
classmethod from_constants(cb_names: str | list[str]) → Self | tuple[Self, ...]#

Create a CelestialBody from a given name using its respective values as defined in constants.

Parameters:
cb_namesstr or list of str

The name or names of the desired body to create a CelestialBody for.

Returns:
cb_outCelestialBody

A CelestialBody object initialized with all relevant values as defined by the given constant value.

Raises:
not_def_err

Raised when the given cb_name does not match an object in Scarabaeus’ constants library.

See also

scarabaeus.Constants

Scarabaeus’ constants library.

Notes

This method performs the same functionality as manually accessing each of the pertinent constants values and assigning them by normal construction. It is a faster alternative when initalizing CelestialBody objects by values from constants.

Examples

Create Jupiter with constants values.

>>> import scarabaeus as scb
>>> jupiter = scb.CelestialBody.from_constants('JUPITER')

Create the Mars system using constants values in one line.

>>> mars, phobos, deimos = scb.CelestialBody.from_constants(['MARS', 'PHOBOS', 'DEIMOS'])
classmethod planets() → list[Self]#

Create each of the eight planets as defined in constants.

Convenience wrapper for from_constants().

Parameters:
None
Returns:
planetslist of CelestialBody

List containing the eight planets with parameters defined by constants:

  • Mercury

  • Venus

  • Earth

  • Mars

  • Jupiter

  • Saturn

  • Uranus

  • Neptune

barycenter() → Self#

Stripped version of the

disp_properties() → None#

Displays all properties of the CelestialBody object in a readable format.

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_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.

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 barycenter_GM: ArrayWUnits | None#

The gravitational parameter of the body’s system barycenter, if defined.

property barycenter_id: int#

The SPICE ID of the object’s barycenter.

property base_frame: Frame#

The reference frame attached to the CelestialBody.

Always a Frame. A name supplied as a string is resolved on first access and cached, so callers never have to test the type. Use base_frame_name when only the name is needed — that accessor never touches SPICE and never raises.

Raises:
CelestialBody.UnresolvedBaseFrameError

If the stored name is not a frame SPICE recognizes, which usually means the required kernels have not been loaded yet.

property base_frame_name: str | None#

Name of the reference frame attached to the CelestialBody.

The plain frame name, whether the frame was supplied as a Frame or as a string. Resolves without SPICE, so it is safe before kernels are loaded and is what should be handed to SPICE-facing routines.

property grav_param: ArrayWUnits | None#

The gravitational parameter of the CelestialBody given, by convention, in units of \(\frac{km^3}{s^2}\), if defined.

property gs_list: list[GroundStation]#

All GroundStation objects attached to the surface of the CelestialBody.

property mass_profile: ArrayWUnits | SCBPolynomial#

Stored constant or polynomial mass profile.

property mean_radius: ArrayWUnits | None#

The mean radius of the CelestialBody, if defined.

property name: str#

The name of the Body object.

property spice_id: int | str#

The SPICE ID of the Body object.

exception InvalidMassError#

Bases: ValueError

The mass is not a constant ArrayWUnits mass, so no GM can be derived from it.

exception UnresolvedBaseFrameError#

Bases: ValueError

The body’s base frame could not be resolved into a Frame.