Skip to main content
Environment modules provide the physical context for your spacecraft simulation: the positions of planets and the sun, atmospheric density, magnetic field vectors, eclipse conditions, and ground station visibility. Most environment modules follow a base-class pattern, writing standardized output messages that sensor and dynamics modules can subscribe to.

​
Ephemeris and time

Reads planetary body positions and orientations from JPL SPICE kernels. This is the primary way to obtain high-fidelity ephemeris data for planets, moons, and spacecraft.Messages
MessageTypeDirectionDescription
spiceTimeOutMsgSpiceTimeMsgPayloadOutputCurrent SPICE time
epochInMsgEpochMsgPayloadInput (optional)Simulation epoch
planetStateOutMsgsSpicePlanetStateMsgPayloadOutput (vector)Celestial body states
scStateOutMsgsSCStatesMsgPayloadOutput (vector)Spacecraft states from kernel
attRefStateOutMsgsAttRefMsgPayloadOutput (vector)Spacecraft attitude reference states
transRefStateOutMsgsTransRefMsgPayloadOutput (vector)Spacecraft translational reference states
from Basilisk.utilities import simIncludeGravBody
from Basilisk.utilities import macros

gravFactory = simIncludeGravBody.gravBodyFactory()
gravFactory.createBodies(['earth', 'mars', 'sun'])

spiceObject = gravFactory.spiceObject
spiceObject.zeroBase = 'earth'
spiceObject.ModelTag = 'SpiceInterface'

# Add specific bodies for state output
spiceObject.addPlanetNames(['earth', 'sun', 'mars'])

sim.AddModelToTask(taskName, spiceObject)
Use addSpacecraftNames() to load spacecraft ephemeris from SPICE kernels when you want to replay flight data or prescribe spacecraft motion.
A lightweight alternative to spiceInterface that provides planet ephemeris data using pre-computed Keplerian elements, without requiring SPICE kernels to be installed. Useful for simple simulations where high-fidelity ephemeris is not needed.
Converts between different ephemeris message formats. Use this module to bridge SpicePlanetStateMsgPayload data into other message types expected by downstream modules.

​
Eclipse

Determines whether each spacecraft in a list is in a solar eclipse and computes the illumination fraction (0.0 = total eclipse, 1.0 = no eclipse). The module uses a conical shadow model with support for umbra, penumbra, and annular eclipse conditions.Messages
MessageTypeDirectionDescription
sunInMsgSpicePlanetStateMsgPayloadInputSun ephemeris
planetInMsgsSpicePlanetStateMsgPayloadInput (vector)Occulting planet states
positionInMsgsSCStatesMsgPayloadInput (vector)Spacecraft positions
eclipseOutMsgsEclipseMsgPayloadOutput (vector)Illumination fraction per spacecraft
from Basilisk.simulation import eclipse

eclipseObject = eclipse.Eclipse()
eclipseObject.ModelTag = 'eclipseObject'

# Connect the sun state message
eclipseObject.sunInMsg.subscribeTo(
    gravFactory.spiceObject.planetStateOutMsgs[sunIndex]
)

# Add occluding bodies and spacecraft
eclipseObject.addPlanetToModel(
    gravFactory.spiceObject.planetStateOutMsgs[earthIndex]
)
eclipseObject.addSpacecraftToModel(scObject.scStateOutMsg)

sim.AddModelToTask(taskName, eclipseObject)

# Access per-spacecraft illumination factor
eclipseLog = eclipseObject.eclipseOutMsgs[0].recorder()
Supported occluding bodies: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Neptune, Uranus, and a single custom body.

​
Atmosphere

All atmosphere modules inherit from atmosphereBase and write AtmoPropsMsgPayload messages consumed by the drag effector and other modules.
Evaluates a simple exponential density model as a function of altitude above a planetary surface. This is the lightest-weight atmosphere model and is appropriate when you need a smooth density profile without space-weather dependence.
from Basilisk.simulation import exponentialAtmosphere

atmo = exponentialAtmosphere.ExponentialAtmosphere()
atmo.ModelTag = 'exponentialAtmo'
atmo.planetRadius = 6371e3      # [m] Earth mean radius
atmo.baseDensity = 1.225        # [kg/m^3] sea-level density
atmo.scaleHeight = 8500.0       # [m] scale height
atmo.addSpacecraftToModel(scObject.scStateOutMsg)

sim.AddModelToTask(taskName, atmo)
High-fidelity atmosphere model using the NRLMSISE-00 empirical model. Supports Venus, Earth, and Mars. Requires 23 space weather input messages covering historical geomagnetic and solar flux indices.Space weather inputs (swDataInMsgs — 23 messages in order):
  • Index 0: ap_24_0 (24-hour average Ap)
  • Indices 1–20: 3-hour Ap values from 0 to -57 hours
  • Index 21: f107_1944_0 (F10.7 flux)
  • Index 22: f107_24_-24 (81-day average F10.7)
Atmosphere model that interpolates density and temperature from a user-supplied data table as a function of altitude. Use this when you have a custom atmospheric profile (e.g., from a climate model or flight data).
A simple atmosphere model that outputs zero wind velocity. Use it as a placeholder when your drag model requires a wind message but you do not want to model wind effects.

​
Magnetic field

All magnetic field modules inherit from magneticFieldBase and write MagneticFieldMsgPayload messages consumed by the magnetometer sensor and magnetic torque bar modules.
Evaluates a centered dipole approximation of a planetary magnetic field at a given spacecraft location. The dipole parameters for Earth are built in.
from Basilisk.simulation import magneticFieldCenteredDipole

magModule = magneticFieldCenteredDipole.MagneticFieldCenteredDipole()
magModule.ModelTag = 'CenteredDipole'
magModule.addSpacecraftToModel(scObject.scStateOutMsg)

sim.AddModelToTask(taskName, magModule)
Evaluates the World Magnetic Model (WMM) for a higher-fidelity Earth magnetic field. The WMM coefficients are loaded from a data file included with Basilisk.
from Basilisk.simulation import magneticFieldWMM

magModule = magneticFieldWMM.MagneticFieldWMM()
magModule.ModelTag = 'WMM'
magModule.addSpacecraftToModel(scObject.scStateOutMsg)

sim.AddModelToTask(taskName, magModule)

​
Ground location

Defines a fixed location on a planetary surface and computes the spacecraft position relative to it in spherical coordinates (range, azimuth, elevation) and South-East-Zenith (SEZ) components. The access output message indicates whether the spacecraft is above the minimum elevation angle.Messages
MessageTypeDirectionDescription
planetInMsgSpicePlanetStateMsgPayloadInput (optional)Planet state for frame conversion
scStateInMsgsSCStatesMsgPayloadInput (vector)Spacecraft state messages
currentGroundStateOutMsgGroundStateMsgPayloadOutputGround location inertial state
accessOutMsgsAccessMsgPayloadOutput (vector)Visibility and range data per spacecraft
from Basilisk.simulation import groundLocation
from Basilisk.utilities import orbitalMotion
import numpy as np

groundStation = groundLocation.GroundLocation()
groundStation.ModelTag = 'Boulder'
groundStation.planetRadius = orbitalMotion.REQ_EARTH * 1000.0  # [m]
groundStation.minimumElevation = np.radians(10.0)  # [rad]
groundStation.maximumRange = -1  # [m] no range limit
groundStation.specifyLocation(
    np.radians(40.0),   # latitude [rad]
    np.radians(-105.0), # longitude [rad]
    1655.0              # altitude [m]
)
groundStation.addSpacecraftToModel(scObject.scStateOutMsg)
groundStation.planetInMsg.subscribeTo(earthMsg)

sim.AddModelToTask(taskName, groundStation)
Similar to groundLocation but maps the spacecraft ground track against a list of target locations, computing per-target access windows and viewing geometry.
Computes the relative position between two spacecraft, analogous to groundLocation but for space-to-space proximity operations.

​
Other environment modules

albedo

Computes the Earth albedo flux seen by a spacecraft, reading planet state and spacecraft state messages to produce an AlbedoMsgPayload consumed by the coarse sun sensor.

solarFlux

Computes solar flux (irradiance) at the spacecraft’s current distance from the sun. Outputs a SolarFluxMsgPayload used by solar panel and SRP models.

spacecraftChargingEquilibrium

Computes the electrostatic charge equilibrium of a spacecraft in a given plasma environment. Consumes plasma density and energy inputs to output a surface potential message.

dentonFluxModel

Provides geosynchronous-orbit plasma flux data using the Denton empirical model. Outputs electron and ion flux messages for charging and plasma interaction modules.

Build docs developers (and LLMs) love

Get started for freeTalk to us