mjorbit

Coupled orbital and multibody dynamics for space robotics.

mjorbit extends MuJoCo with a propagated reference orbit and spacecraft interaction with gravity gradients, J2, drag, solar radiation pressure, and magnetic fields. It supports articulated spacecraft, contact, spacecraft actuators, and parallel rollouts for control and learning.

Project page · Paper · Documentation · Examples · Paper reproduction

Install Pixi, then run:

git clone https://github.com/johnzhang3/mjorbit.git
cd mjorbit
pixi install
pixi run viewer --task free_drift

Open the printed URL, normally http://localhost:8080, to see a dual-arm spacecraft orbiting Earth. Use Pause, Reset, and the task dropdown to explore. The initial installation builds the C++ extension; Pixi supplies the compiler and build tools. No GPU or trained checkpoint is needed for this demo.

For a numerical example without a browser:

pixi run example-minimal
pixi run example-free-drift  # comparison with a Clohessy–Wiltshire reference

Python 3.11–3.12 is supported. The CPU environments cover Linux x86-64 and macOS Intel/Apple Silicon. GPU and RL environments target Linux x86-64 with an NVIDIA GPU. See installation for optional environments and instructions for using mjorbit from another project.

import numpy as np

from mjorbit import MjoModel, OrbitInit, mjo_forward, mjo_step
from mjorbit.constants import GM_EARTH, R_EARTH
from mjorbit.testdata import FREE_BODY_XML

radius_km = R_EARTH + 400.0
model = MjoModel.from_xml_path(FREE_BODY_XML, mj_timestep=0.01)
data = model.make_data(
    orbit=OrbitInit(
        R_eci=[radius_km, 0.0, 0.0],
        V_eci=[0.0, np.sqrt(GM_EARTH / radius_km), 0.0],
    )
)
data.qpos[:3] = [10.0, 0.0, 0.0]  # offset from the chief, in meters
mjo_forward(model, data)

for _ in range(100):
    mjo_step(model, data)

print(f"Time: {data.time:.2f} s")
print("Chief position (km):", data.orbit.R_eci)
print("Spacecraft offset (m):", data.qpos[:3])

This advances one second. The chief moves along its orbit while the spacecraft stays approximately 10 m away. The quick-start tutorial explains the XML model, initial conditions, and output.

Frames and units: OrbitInit and data.orbit use absolute ECI position in km and velocity in km/s. MuJoCo world is a chief-centered local inertial frame with axes parallel to ECI; qpos and qvel use SI offsets. LVLH is a derived rotating frame. Spacecraft actuator commands use SI units (N·m, A·m², N, rad/s); see frames and units before applying forces or torques.

Choose a backend explicitly by import path. Both use the MjoModel → model.make_data(...) → mjo_step(...) workflow.

pixi install -e warp
pixi run -e warp example-batched

The complete batched example uses a bundled model and shows mjo_upload and mjo_pull. The GPU guide explains shapes, precision, synchronization, and current limitations.

See the example catalog for viewer options, duration, requirements, and training/playback instructions. Experiments contains paper benchmarks and figure generators. Recording tools produce videos from simulated trajectories. These remain in the source repository and source distribution; they are not installed as runtime packages.

Browse the documentation sources, or build a local site:

pixi run -e docs docs-build
pixi run -e docs docs-serve  # http://localhost:8000

pixi run lint
pixi run typecheck
pixi run test
pixi run cpp-test
pixi run package-check     # isolated wheel and source-distribution installs

See CONTRIBUTING.md for development guidance and RELEASING.md for release checks.

If you use mjorbit in your research, please cite mjorbit: A Simulation Framework for Space Robotics. Software and preferred paper citation metadata are in CITATION.cff.

@article{zhang2026mjorbit,
  title   = {mjorbit: A Simulation Framework for Space Robotics},
  author  = {Zhang, John Z. and Verhagen, Joris and Vega, Fausto
             and McKeen, Patrick and Manchester, Zachary},
  journal = {arXiv preprint arXiv:2609.08010},
  year    = {2026},
  eprint  = {2609.08010},
  archivePrefix = {arXiv},
  primaryClass = {cs.RO},
  url     = {https://arxiv.org/abs/2609.08010}
}

Original project code and documentation are licensed under Apache 2.0. Third-party assets retain their own terms; see NOTICE and the docking asset provenance notes.