simIncludeGravBody

Create gravity-body descriptors and connect them to Basilisk dynamics.

The usual workflow is to create the bodies first, mark one body as central when appropriate, and then attach the factory bodies to a dynamics object:

from Basilisk.utilities import simIncludeGravBody

gravFactory = simIncludeGravBody.gravBodyFactory()
earth = gravFactory.createEarth()
earth.isCentralBody = True
gravFactory.addBodiesTo(spacecraftObject)

The same addBodiesTo() call accepts a MuJoCo MJScene. In that case the factory creates the intermediate NBodyGravity model and connects every MuJoCo body as a gravity target.

Call createSpiceInterface() after creating the gravity bodies. The factory then connects each body’s ephemeris input to the corresponding SPICE output.

class simIncludeGravBody.BodyData(identifier: str, planetName: str, displayName: str, modelDictionaryKey: str, mu: float, radEquator: float, spicePlanetFrame: str, radiusRatio: float = 1)[source]

Bases: object

A class that contains information about a body in the simulation.

Parameters:

  • identifier (str) – The SPICE identifier of the body.

  • planetName (str) – The name that identifies the body within the simulation.

  • displayName (str) – The name for the body in the Vizard display.

  • modelDictionaryKey (str) – Vizard model key name.

  • mu (float) – Gravitational parameter in m^3/s^2.

  • radEquator (float) – Equatorial radius of the body in meters.

  • spicePlanetFrame (str) – The name of the SPICE frame (attitude provider).

  • radiusRatio (float, optional) – Used to compute ellipticity. It is provided for bodies in the basic Vizard body dictionary. Defaults to 1.

class simIncludeGravBody.WithGravField(*args, **kwargs)[source]

Bases: Protocol

class simIncludeGravBody.WithSetGravBodies(*args, **kwargs)[source]

Bases: Protocol

class simIncludeGravBody.gravBodyFactory(bodyNames: Iterable[str] = [])[source]

Bases: object

Create and retain the gravity bodies used by a simulation.

gravBodies is the factory’s canonical dictionary of GravBodyData descriptors. A descriptor can be shared by conventional spacecraft dynamics, MuJoCo dynamics, SPICE, and Vizard without copying its gravity model or configuration.

addBodiesTo(objectToAddTheBodies: Any) → Any | None[source]

Attach the factory’s gravity bodies to a dynamics object.

A conventional dynamics object may be a GravityEffector or expose a gravField attribute. When an MJScene is provided, this method creates one NBodyGravity model, adds every factory body as a gravity source, and adds every MuJoCo body as a gravity target.

Parameters:

objectToAddTheBodies (Any) – Dynamics object that should receive the factory’s gravity bodies.

Returns:

The created NBodyGravity model for an MJScene;

otherwise, None.

Return type:

Optional[Any]

Raises:

  • TypeError – If the supplied object is not a supported dynamics object.

  • ValueError – If gravity was already attached to the MJScene.

Note

When factory bodies use SPICE ephemerides, add the factory’s spiceObject to the MJScene dynamics task before calling this method. This keeps planet states current at each MuJoCo integrator substep.

createBodies(*bodyNames: str | Iterable[str]) → Dict[str, GravBodyData][source]

A convenience function to create multiple typical solar system bodies.

Parameters:

bodyNames (Union[str, Iterable[str]]) – Planet name strings. Each planet name must be a valid SPICE celestial body string.

Returns:

A dictionary of gravity body objects held by the gravity factory.

Return type:

Dict[str, gravityEffector.GravBodyData]

createBody(bodyData: str | BodyData) → GravBodyData[source]

Convenience function to create a body given its name.

Parameters:

bodyData (Union[str, BodyData]) – A valid SPICE celestial body string or a BodyData class with the relevant data.

Returns:

The body object with corresponding data.

Return type:

gravityEffector.GravBodyData

createCustomGravObject(label: str, mu: float, displayName: str | None = None, modelDictionaryKey: str | None = None, radEquator: float | None = None, radiusRatio: float | None = None, planetFrame: str | None = None) → GravBodyData[source]

Create a custom gravity body object.

Parameters:

  • label (str) – Gravity body name.

  • mu (float) – Gravitational parameter in m^3/s^2.

  • displayName (Optional[str], optional) – Vizard celestial-body name. If omitted, Vizard uses the gravity body’s planetName. Defaults to None.

  • modelDictionaryKey (Optional[str], optional) – Vizard model key name. If not set, then either the displayName or planetName is used to set the model. Defaults to None.

  • radEquator (Optional[float], optional) – Equatorial radius in meters. Defaults to None.

  • radiusRatio (Optional[float], optional) – Ratio of the polar radius to the equatorial radius. Defaults to None.

  • planetFrame (Optional[str], optional) – Name of the SPICE planet frame. Defaults to None.

Returns:

The body object with the given data.

Return type:

gravityEffector.GravBodyData

createSpiceInterface(path: str, time: str, spiceKernelFileNames: Iterable[EphemerisData] = (DataFile.EphemerisData.de430, DataFile.EphemerisData.naif0012, DataFile.EphemerisData.de_403_masses, DataFile.EphemerisData.pck00010), spicePlanetNames: Sequence[str] | None = None, spicePlanetFrames: Sequence[str] | None = None, epochInMsg: bool = False) → SpiceInterface[source]
createSpiceInterface(*, path: str = '%BSK_PATH%/supportData/EphemerisData/', time: str, spiceKernelFileNames: Iterable[EphemerisData] = (DataFile.EphemerisData.de430, DataFile.EphemerisData.naif0012, DataFile.EphemerisData.de_403_masses, DataFile.EphemerisData.pck00010), spicePlanetNames: Sequence[str] | None = None, spicePlanetFrames: Sequence[str] | None = None, epochInMsg: bool = False) → SpiceInterface

Configure a NAIF SPICE module for the simulation.

This method connects the factory’s GravBodyData objects to the corresponding SPICE planet-state messages. It must therefore be called after the gravity bodies are created.

Unless the path input is provided, the kernels are loaded from the folder: %BSK_PATH%/supportData/EphemerisData/, where %BSK_PATH% is replaced by the Basilisk directory.

Note

spicePlanetFrames specifies the output frames used to compute J20002Pfix for each planet state output message. If this argument is not set, the method uses the frames gathered when bodies were created (typically IAU_* frame names).

Alternatives to IAU_* can be provided as long as SPICE can resolve the frame IDs from loaded kernels. For example, "ITRF93" can be used for Earth-fixed outputs when Earth high precision kernels are available, and "J2000" can be used to request an inertial-aligned output frame.

Earth frame-association FK kernels (for example earth_assoc_itrf93.tf) do not override spicePlanetFrames.

Parameters:

  • path (str) – The absolute path to the folder that contains the kernels to be loaded.

  • time (str) – The time string in a format that SPICE recognizes.

  • spiceKernelFileNames (Iterable[DataFile.EphemerisData], optional) – Support-data entries for the SPICE kernels to load. Defaults to de430.bsp, naif0012.tls, de-403-masses.tpc, and pck00010.tpc.

  • spicePlanetNames (Optional[Sequence[str]], optional) – Planet names whose SPICE data is loaded. If omitted, the method uses the bodies created with this factory, in insertion order. Defaults to None.

  • spicePlanetFrames (Optional[Sequence[str]], optional) – Planet frame names to load in SPICE. If omitted, the method uses the frames recorded when the factory bodies were created. Defaults to None.

  • epochInMsg (bool, optional) – If True, create and connect an epoch input message. Defaults to False.

  • spiceKernalFileNames – Deprecated misspelling of spiceKernelFileNames.

Returns:

The generated SpiceInterface.

The same object is also available as self.spiceObject.

Return type:

spiceInterface.SpiceInterface

unloadSpiceKernels()[source]

Unload this factory’s SPICE kernels at the end of a simulation.

simIncludeGravBody.loadGravFromFile(fileName: str, spherHarm: SphericalHarmonicsGravityModel, maxDeg: int = 2)[source]

Load the gravitational body spherical harmonics coefficients from a file.

This wrapper delegates to gravityEffector.loadGravFromFile().

Parameters:

  • fileName (str) – The full path to the specified data file.

  • spherHarm (gravityEffector.SphericalHarmonicsGravityModel) – The spherical harmonics container of the gravity body.

  • maxDeg (int, optional) – Maximum degree of spherical harmonics to load. Defaults to 2.

simIncludeGravBody.loadPolyFromFile(fileName: str, poly: PolyhedralGravityModel)[source]

Load the gravitational body polyhedral coefficients from a file.

Parameters:

  • fileName (str) – The full path to the specified data file.

  • poly (gravityEffector.PolyhedralGravityModel) – The polyhedral gravity model container of the body.