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:
BodyDefines 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_paramwhen omitted. Defaults toNone.- 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
masswhen omitted. Defaults toNone.- 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_GMThe gravitational parameter of the body’s system barycenter, if defined.
barycenter_idThe SPICE ID of the object’s barycenter.
base_frameThe reference frame attached to the CelestialBody.
base_frame_nameName of the reference frame attached to the CelestialBody.
grav_paramThe gravitational parameter of the CelestialBody given, by convention, in units of \(\frac{km^3}{s^2}\), if defined.
gs_listAll GroundStation objects attached to the surface of the CelestialBody.
mass_profileStored constant or polynomial mass profile.
mean_radiusThe mean radius of the CelestialBody, if defined.
nameThe name of the Body object.
spice_idThe SPICE ID of the Body object.
Methods
Stripped version of the
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.
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.constantsScarabaeus’ constants library, including planetary constants.
scarabaeus.FrameScarabaeus’ 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 thanmassfor orbital computations to avoid rounding errors from \(G\).Only one of
massandgrav_paramis needed: the missing one is derived through \(\mu = GM\) withConstants.G. When both are given, both are kept as supplied. When neither is given, both stayNone, 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_namedoes not match an object in Scarabaeus’ constants library.
See also
scarabaeus.ConstantsScarabaeus’ 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
- 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 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. Usebase_frame_namewhen 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
Frameor 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.
- exception InvalidMassError#
Bases:
ValueErrorThe mass is not a constant ArrayWUnits mass, so no GM can be derived from it.
- exception UnresolvedBaseFrameError#
Bases:
ValueErrorThe body’s base frame could not be resolved into a
Frame.