Skip to main content
This guide walks you through the canonical scenarioBasicOrbit example: a spacecraft propagating around Earth using point-mass gravity. By the end you will have a working simulation that records position and velocity, then plots the orbit.

​
Prerequisites

Install Basilisk and download the example scripts: 
pip install bsk
The bskExamples command copies the examples/ folder into your current working directory. Work from this local copy — do not edit files inside the installed package.
Run bskLargeData once after installing to pre-download gravity model and ephemeris files, so the simulation does not fetch them on first run.

​
Build the simulation

1

Import modules

Every Basilisk simulation starts with the same set of imports. The spacecraft module provides the 6-DOF dynamics model; the utilities supply the simulation container, unit converters, and gravity body factories.
import numpy as np
import matplotlib.pyplot as plt

from Basilisk.simulation import spacecraft
from Basilisk.utilities import (
    SimulationBaseClass,
    macros,
    orbitalMotion,
    simIncludeGravBody,
    unitTestSupport,
)
2

Create the simulation container

SimBaseClass is the top-level container for every Basilisk simulation. All processes, tasks, and modules attach to this object.
scSim = SimulationBaseClass.SimBaseClass()

# Optional: display a progress bar in the terminal
scSim.SetProgressBar(True)
3

Create a process and add a dynamics task

Basilisk organizes execution into processes (parallel execution groups) and tasks (ordered lists of modules within a process). The integration step size is set here in nanoseconds.
simProcessName = "simProcess"
simTaskName = "simTask"

dynProcess = scSim.CreateNewProcess(simProcessName)

simulationTimeStep = macros.sec2nano(10.0)  # 10-second integration step
dynProcess.addTask(scSim.CreateNewTask(simTaskName, simulationTimeStep))
4

Set up the spacecraft

Instantiate a Spacecraft module and add it to the dynamics task. The ModelTag is a human-readable label used in logging and Vizard visualization.
scObject = spacecraft.Spacecraft()
scObject.ModelTag = "bsk-Sat"

scSim.AddModelToTask(simTaskName, scObject)
5

Add a gravity body

Use gravBodyFactory to create a gravitational body and attach it to the spacecraft. Setting isCentralBody = True marks Earth as the primary attractor.
gravFactory = simIncludeGravBody.gravBodyFactory()

earth = gravFactory.createEarth()
earth.isCentralBody = True

gravFactory.addBodiesTo(scObject)

mu = earth.mu  # gravitational parameter [m^3/s^2]
To simulate Mars instead, call gravFactory.createMarsBarycenter() and set isCentralBody = True on that object. To add spherical harmonics, call planet.useSphericalHarmonicsGravityModel(path, degree) before connecting the factory to the spacecraft.
6

Set initial orbit conditions

Define a Low Earth Orbit (LEO) using classical orbital elements, then convert to inertial position and velocity vectors to initialize the spacecraft state.
oe = orbitalMotion.ClassicElements()
rLEO = 7000.0e3  # semi-major axis [m], ~7000 km

oe.a = rLEO
oe.e = 0.0001         # near-circular
oe.i = 33.3 * macros.D2R   # inclination [rad]
oe.Omega = 48.2 * macros.D2R  # RAAN [rad]
oe.omega = 347.8 * macros.D2R  # argument of perigee [rad]
oe.f = 85.3 * macros.D2R      # true anomaly [rad]

rN, vN = orbitalMotion.elem2rv(mu, oe)

scObject.hub.r_CN_NInit = rN  # inertial position [m]
scObject.hub.v_CN_NInit = vN  # inertial velocity [m/s]
7

Set simulation time and configure data logging

Compute the orbital period and run for 75% of one orbit. Attach a recorder to the spacecraft’s state output message to capture position and velocity at regular intervals.
n = np.sqrt(mu / oe.a**3)          # mean motion [rad/s]
P = 2.0 * np.pi / n                # orbital period [s]
simulationTime = macros.sec2nano(0.75 * P)

numDataPoints = 100
samplingTime = unitTestSupport.samplingTime(
    simulationTime, simulationTimeStep, numDataPoints
)

dataRec = scObject.scStateOutMsg.recorder(samplingTime)
scSim.AddModelToTask(simTaskName, dataRec)
8

Initialize and run the simulation

InitializeSimulation runs self_init() and reset() on every module. ConfigureStopTime and ExecuteSimulation advance the simulation to the specified end time.
scSim.InitializeSimulation()
scSim.ConfigureStopTime(simulationTime)
scSim.ExecuteSimulation()
9

Retrieve and plot results

Access the recorded data directly from the recorder object. Times are in nanoseconds; convert using macros.NANO2SEC.
posData = dataRec.r_BN_N   # inertial position [m], shape (N, 3)
velData = dataRec.v_BN_N   # inertial velocity [m/s], shape (N, 3)
timeAxis = dataRec.times()  # time stamps [ns]

# Plot inertial position components
plt.figure(1)
for idx in range(3):
    plt.plot(
        timeAxis * macros.NANO2SEC / P,
        posData[:, idx] / 1000.0,
        label=f"$r_{{BN,{idx}}}$",
    )
plt.xlabel("Time [orbits]")
plt.ylabel("Inertial Position [km]")
plt.legend()
plt.show()

​
Run the complete example

After downloading the examples with bskExamples, run the full scenario directly: 
python scenarioBasicOrbit.py
The script accepts parameters for orbit type (LEO, GEO, GTO), planet (Earth, Mars), and whether to enable spherical harmonic gravity. These are set at the bottom of the file under the if __name__ == "__main__": block.

​
Next steps

Core concepts

Learn how processes, tasks, and message-passing work together.

Attitude feedback tutorial

Add a 3-DOF attitude controller to the spacecraft.

Vizard visualization

Connect the 3D Vizard application to view your simulation live.

Build from source

Link custom C++ modules or enable optional build features.

Build docs developers (and LLMs) love

Get started for freeTalk to us