Skip to main content

​
Overview

Basilisk’s gravity system is split between the GravityEffector (built into Spacecraft) and swappable GravityModel objects. The two primary models are:
  • Point-mass (GravBodyData) — simple µ/r² gravity, adequate for most mission analysis.
  • SphericalHarmonicsGravityModel — full J2..Jn gravity using normalized C/S coefficients.
from Basilisk.simulation import gravityEffector
from Basilisk.simulation import spacecraft

​
GravBodyData

Defines a gravitating body (planet, moon, sun) attached to the spacecraft’s gravField.
​
planetName
str
SPICE body name used to look up ephemeris data (e.g., "earth_planet_data").
​
mu
double
Gravitational parameter µ = G·M [m³/s²].
​
isCentralBody
bool
Set True for the primary attracting body. Only one central body is allowed.
​
useSphericalHarmParams
bool
Set True to use the attached SphericalHarmonicsGravityModel instead of a point mass.

​
SphericalHarmonicsGravityModel

Computes the gravitational acceleration using a spherical harmonics expansion.

​
Configuration parameters

​
radEquator
double
Reference equatorial radius of the body [m].
gravModel.radEquator = 6378136.6  # [m]
​
muBody
double
Gravitational parameter [m³/s²].
gravModel.muBody = 3.986004418e14  # [m^3/s^2]
​
maxDeg
size_t
Maximum degree of spherical harmonics to evaluate. Must not exceed the size of cBar / sBar.
gravModel.maxDeg = 70
​
cBar
list[list[double]]
Normalized C (cosine) spherical harmonics coefficients. Indexed as cBar[n][m].
​
sBar
list[list[double]]
Normalized S (sine) spherical harmonics coefficients. Indexed as sBar[n][m].

​
Key methods

​
initializeParameters()
method
Validates that cBar and sBar are set and pre-computes internal recursion coefficients. Called automatically during Spacecraft.Reset().Returns an optional error string; empty means success.
​
computeField(position_planetFixed)
method
Returns the gravitational acceleration vector at the given body-fixed position [m/s²].
Eigen::Vector3d acc = gravModel.computeField(pos_bf);
An overload accepts (position, degree, include_zero_degree) to truncate the expansion at a lower degree.

​
Loading coefficients from a file

Use the helper gravCoeffOps to read standard EGM coefficient files: 
from Basilisk.simulation import gravityEffector

earth = gravityEffector.GravBodyData()
earth.planetName        = "earth_planet_data"
earth.isCentralBody     = True
earth.useSphericalHarmParams = True

gravityEffector.loadGravFromFile(
    "GGM03S.txt",   # EGM-format coefficient file
    earth.spherHarm,
    70,             # maximum degree
)

​
Attaching gravity to a spacecraft

from Basilisk.simulation import spacecraft, gravityEffector

scObject = spacecraft.Spacecraft()
scObject.ModelTag = "bsk-Sat"

earth = gravityEffector.GravBodyData()
earth.planetName    = "earth_planet_data"
earth.mu            = 3.986004418e14   # [m^3/s^2]
earth.isCentralBody = True

scObject.gravField.gravBodies = spacecraft.GravBodyVector([earth])

Build docs developers (and LLMs) love

Get started for freeTalk to us