Cosmic Code Hackathon 2026 · BMS College of Engineering
Explore. Perturb. Simulate. Understand.
Celestia is an interactive orbital dynamics laboratory for studying the Circular Restricted Three-Body Problem (CR3BP), Lagrange-point equilibria, orbital stability, perturbation response, and rotating-frame dynamics.
Demo-compressed.mp4
Celestia in action — from system configuration to numerical simulation, rotating-frame visualization, telemetry, and cinematic rendering.
Celestia is an interactive numerical laboratory designed to make the mathematics and dynamics of the Circular Restricted Three-Body Problem tangible.
Instead of simply displaying precomputed Lagrange points, Celestia allows the user to:
- configure two gravitationally interacting primary bodies;
- calculate the corresponding mass ratio
μ; - dynamically solve for all five Lagrange points;
- inspect the effective gravitational potential;
- select an equilibrium point;
- deliberately perturb a test satellite;
- numerically integrate its subsequent motion;
- transform the resulting trajectory into the rotating reference frame;
- analyze the stability of the selected equilibrium;
- inspect telemetry such as deviation, Jacobi constant, mass ratio, and orbital period;
- and finally render the simulation as a cinematic orbital animation.
The result is a complete pipeline:
MASSIVE BODIES
│
▼
Mass Ratio μ
│
▼
Lagrange Point Solver
│
┌──────┴──────┐
▼ ▼
Equilibrium Potential
Geometry Landscape
│
▼
Satellite Placement
│
▼
Position / Velocity
Perturbation
│
▼
REBOUND + IAS15
│
▼
Inertial Trajectory
│
▼
Rotating-Frame Transform
│
├───────────────┐
▼ ▼
Stability Visualization
Analysis + Telemetry
│ │
└───────┬───────┘
▼
Cinematic Export
Manim
Most educational demonstrations of Lagrange points stop at showing five markers around two bodies.
Celestia goes further.
It combines analytical orbital mechanics, numerical root finding, high-accuracy N-body integration, linear stability analysis, reference-frame transformations, and interactive scientific visualization into one environment.
The central question is not:
"Where are the Lagrange points?"
It is:
"What happens when we disturb a satellite from one of them?"
That distinction is the foundation of the project.
Celestia uses the Circular Restricted Three-Body Problem (CR3BP).
The system consists of:
- A primary body with mass
m₁ - A secondary body with mass
m₂ - A massless satellite / test particle
The satellite experiences the gravitational influence of both primary bodies, while its own mass is assumed negligible.
The two primaries orbit their common barycenter.
The system is parameterized by:
where:
m₁= primary massm₂= secondary massμ= normalized mass ratio
Celestia calculates this dynamically from the selected bodies.
In normalized CR3BP coordinates, the barycenter is placed at the origin and the primaries are positioned at:
This coordinate system is used throughout the Lagrange-point calculations.
Celestia calculates all five classical equilibrium points dynamically, combining numerical root-finding with analytical geometry.
The three collinear points lie along the axis connecting the two primary bodies. They are found by solving the nonlinear equilibrium equation:
We utilize scipy.optimize.brentq for robust bracketed root solving (with a Newton-method fallback) to locate these points:
- L1: Between the two primary bodies.
- L2: Beyond the secondary body.
- L3: Beyond the primary body on the opposite side.
The L4 and L5 points have an elegant, analytical closed-form solution. They form equilateral triangles with the primary bodies:
Celestia also calculates the effective potential in the rotating frame:
where:
and
The effective potential is used to generate the interactive 3D Potential Terrain visualization.
This provides a geometric interpretation of the gravitational and centrifugal structure of the rotating frame.
Celestia does not simply hard-code the stability labels.
The selected equilibrium point is locally linearized.
The Hessian of the effective potential is estimated numerically:
using central finite differences.
These derivatives are then used to construct the linearized rotating-frame system:
Celestia calculates the eigenvalues of this matrix.
The equilibrium is classified according to the real parts of those eigenvalues:
positive real eigenvalue
↓
unstable
no positive real component
↓
stable
This allows the application to distinguish stable and unstable equilibrium behavior using the local dynamics of the system rather than purely visual rules.
This is the central interactive experiment in Celestia.
After selecting a Lagrange point, the satellite can be displaced using three independent controls:
Radial perturbation
Moves the satellite toward or away from the equilibrium region.
Tangential perturbation
Moves the satellite sideways relative to the selected point.
Velocity perturbation
Adds an additional velocity component to the satellite's initial state.
The resulting state becomes:
Ideal equilibrium state
+
position perturbation
+
velocity perturbation
↓
Numerical initial conditions
↓
Orbital evolution
This allows users to experimentally observe the difference between an equilibrium configuration and a perturbed trajectory.
The actual orbital evolution is performed using REBOUND.
Celestia creates a normalized gravitational simulation with:
sim.G = 1.0
sim.integrator = "ias15"The two primary bodies are initialized in circular motion around their barycenter.
The satellite is inserted as a:
m = 0.0massless test particle.
This is consistent with the restricted three-body approximation: the satellite responds to the gravitational field but does not modify the motion of the two primary bodies.
Celestia uses REBOUND's IAS15 integrator.
IAS15 is a high-accuracy adaptive integrator designed for gravitational dynamics.
This is particularly useful for Celestia because the application is not merely trying to produce visually plausible trajectories.
It is investigating the response of a satellite to small changes in its initial state.
Numerical accuracy therefore matters.
REBOUND evolves the system in an inertial reference frame.
However, Lagrange points are stationary only when viewed from the rotating frame of the two-body system.
Celestia therefore transforms the numerical trajectory.
For:
the rotating-frame coordinates are:
This transformation is implemented in frames.py using vectorized NumPy operations.
The result is a trajectory that can be interpreted relative to the moving primary bodies and their equilibrium points.
Once a simulation has been generated, Celestia exposes numerical telemetry including:
| Metric | Meaning |
|---|---|
| Maximum Deviation | Largest displacement of the simulated trajectory from its starting point |
| Jacobi Constant | Rotating-frame conserved quantity used to characterize the trajectory |
| Mass Ratio μ | Normalized secondary-to-total mass ratio |
| Orbital Period | Characteristic orbital period calculated from the system parameters |
The Jacobi constant is calculated as:
This provides an additional dynamical quantity alongside the visual trajectory.
Celestia provides multiple visualization modes.
The primary scientific view.
It displays:
- primary bodies;
- barycentric geometry;
- L1–L5;
- L4/L5 triangular geometry;
- satellite trajectory;
- rotating-frame motion;
- interactive map selection;
- animated trajectory playback.
The effective potential is sampled over a spatial grid and rendered as an interactive 3D surface.
This gives the user a visual representation of the underlying rotating-frame potential field.
It is particularly useful for understanding why equilibrium points exist and how the gravitational landscape changes around the system.
The cinematic visualization presents the same numerical simulation as a polished orbital animation.
It includes:
- rotating primary bodies;
- Lagrange points;
- orbital paths;
- satellite motion;
- trajectory history;
- starfield;
- dynamic labels;
- playback controls.
The visualization is generated with Plotly and animated through frame updates.
Celestia also contains a dedicated Manim rendering pipeline.
The trajectory generated by the numerical simulation can be passed into manim_viz.py.
The renderer creates:
- a deep-space environment;
- dynamically scaled primary bodies;
- glowing orbital objects;
- body labels;
- a live satellite probe;
- rotating-frame motion;
- trajectory traces;
- an inertial trail;
- smooth animation.
The final output is rendered as an MP4 animation.
This creates a separation between:
Scientific computation
↓
Numerical trajectory
↓
Interactive visualization
↓
Presentation-quality rendering
The scientific result and the cinematic presentation therefore use the same underlying trajectory.
Celestia includes a built-in mass catalogue containing:
- Sun
- Mercury
- Venus
- Earth
- Moon
- Mars
- Jupiter
- Saturn
- Uranus
- Neptune
- Pluto
- Custom
The system can therefore be used to explore a range of mass ratios.
Custom bodies can also be configured manually.
When both bodies are set to Custom, the orbital map can be used interactively to place the two bodies and derive their separation from the selected coordinates.
A typical Celestia experiment looks like this:
Choose the primary and secondary bodies.
Primary Body
Secondary Body
Separation
Celestia calculates:
The five Lagrange points are calculated dynamically.
L4
◆
L3 ◆ ─── Primary ─── L1 ─── Secondary ─── ◆ L2
◆
L5
Choose:
L1
L2
L3
L4
L5
The interface displays the corresponding stability classification.
Adjust:
Move in / out
Move sideways
Velocity trim
Celestia initializes REBOUND and numerically integrates the system using IAS15.
The inertial trajectory is converted into rotating-frame coordinates.
Inspect:
- trajectory shape;
- stability;
- maximum deviation;
- Jacobi constant;
- mass ratio;
- orbital period.
Export the simulation as a cinematic Manim animation.
Celestia's codebase is designed with a strict separation of concerns, ensuring scientific rigor while maintaining an interactive, real-time user interface.
app.py — The Application Core
Orchestrates the entire Streamlit application. It manages the UI layout, captures user input for system configuration and perturbations, and wires together the physics engine, numerical simulation, and rendering pipelines.
Key responsibilities: State management, Telemetry display, Video export triggering.
physics.py — CR3BP Mathematics
The analytical heart of Celestia. Implements the Circular Restricted Three-Body Problem equations, dynamically calculating the normalized mass ratio (μ) and the precise coordinates of the five Lagrange points.
Key methods:compute_L1,compute_L2,compute_L3, Eigenvalue stability analysis, Jacobi constant derivation.
rebound_sim.py — Numerical Dynamics Engine
Wraps the powerful REBOUND N-body library. Initializes the primary bodies and the test satellite, then performs high-accuracy numerical integration using the IAS15 integrator to trace the perturbed trajectory over time.
frames.py — Coordinate Transformations
A dedicated module for translating the inertial trajectories calculated by REBOUND into the rotating reference frame of the two primary bodies, making the Lagrange points appear stationary.
viz.py & manim_viz.py — The Visualization Layer
viz.py: Uses Plotly to render the interactive 2D orbital plane and the rich 3D potential terrain.
manim_viz.py: An advanced rendering pipeline using Manim to export the numerical simulation into a presentation-quality, cinematic MP4 animation.
celestia/
├── app.py # Main Streamlit UI & Orchestration
├── physics.py # CR3BP Math, Lagrange solvers, Stability
├── rebound_sim.py # REBOUND/IAS15 numerical integration
├── frames.py # Inertial → Rotating transformations
├── viz.py # Plotly 2D/3D Interactive graphics
├── manim_viz.py # Manim Cinematic MP4 generation
├── requirements.txt # Dependencies
└── logo.png # Visual identity
| Technology | Role |
|---|---|
| Python | Core implementation |
| Streamlit | Interactive scientific application |
| NumPy | Numerical computation and vectorization |
| SciPy | Numerical root finding |
| REBOUND | Gravitational N-body integration |
| IAS15 | High-accuracy numerical integrator |
| Plotly | Interactive 2D/3D visualization |
| Manim | Cinematic scientific rendering |
| FFmpeg | Video encoding / rendering dependency |
Celestia requires:
- Python 3.x
pip- FFmpeg
- a system capable of running Streamlit and the Manim rendering stack
FFmpeg is required for the cinematic video-rendering pipeline.
The easiest way to run Celestia is to use the pre-packaged standalone executables. You do not need Python or any dependencies installed.
- Go to the Releases page of this repository.
- Download the executable for your operating system:
- Windows: Download
Celestia-Windows.exe - Mac: Download
Celestia-macOS
- Windows: Download
- Double-click the downloaded file to run it.
- A local server will start in the background, and your default web browser will automatically open Celestia!
(Note: On Mac, you may need to right-click the file and select "Open" to bypass the unrecognized developer warning, or grant it execute permissions via terminal: chmod +x Celestia-macOS).
Clone the repository:
git clone https://github.com/priyanshusharan-cmd/celestia.git
cd celestiaInstall the Python dependencies:
pip install -r requirements.txtLaunch Celestia:
streamlit run app.pyStreamlit will provide a local URL where the Orbital Dynamics Laboratory can be opened in your browser.
A simple first experiment is an Earth–Moon configuration.
Select:
Primary Body → Earth
Secondary Body → Moon
Select:
L4
Leave the perturbations near zero.
Observe the trajectory in the rotating reference frame.
Increase the position or velocity perturbation.
Compare the resulting trajectory with the equilibrium configuration.
Repeat the experiment with L1, L2, L3, L4 and L5 to observe the dramatically different dynamical behavior.
Celestia's CR3BP calculations use normalized dynamical units internally.
The canonical geometry uses:
Barycenter = (0, 0)
Primary 1 = (-μ, 0)
Primary 2 = (1-μ, 0)
The physical system is then scaled according to the selected masses and separation.
This normalization allows the same mathematical machinery to work across systems with radically different physical scales.
Celestia is intentionally based on the Circular Restricted Three-Body Problem.
Therefore, the model makes important simplifying assumptions.
- the two primary bodies form the dominant gravitational system;
- their orbits are approximately circular;
- the satellite has negligible mass;
- relativistic effects are ignored;
- non-gravitational forces are ignored;
- atmospheric drag is ignored;
- solar radiation pressure is ignored;
- planetary ephemerides are not used;
- the primary bodies are treated as point masses.
Therefore, Celestia should be understood as a scientific simulation and educational laboratory, not as a flight-certified mission-design system.
For real mission planning, higher-fidelity ephemerides and additional perturbation models would be required.
Celestia was designed around three principles:
The visualization should be generated from the numerical model rather than being a decorative animation disconnected from the physics.
Users should be able to perturb an equilibrium and observe the dynamical consequence.
Complex orbital mechanics does not need to be presented through an intimidating research interface.
Celestia combines numerical rigor with a visual language inspired by spacecraft mission-control systems and deep-space instrumentation.
Possible extensions include:
- higher-fidelity planetary ephemerides;
- non-circular restricted three-body dynamics;
- solar radiation pressure;
- atmospheric drag models;
- spacecraft finite-mass modeling;
- halo and Lissajous orbit analysis;
- zero-velocity surface visualization;
- automated stability maps;
- trajectory optimization;
- fuel / Δv analysis;
- Lambert-transfer calculations;
- multi-spacecraft simulations;
- 3D spatial trajectories;
- mission-design presets for real Earth–Moon and Sun–Earth missions.
Celestia is built around classical concepts from:
- celestial mechanics;
- the Circular Restricted Three-Body Problem;
- rotating reference frames;
- gravitational potential theory;
- Lagrange equilibrium points;
- linear stability analysis;
- numerical ordinary differential equation integration;
- N-body gravitational dynamics.
The implementation intentionally exposes these concepts through interactive computation rather than treating them as static educational material.
- Mathematical Model: CR3BP + dynamically solved Lagrange points
- Numerical Engine: REBOUND + IAS15
- Stability: Linearized rotating-frame eigenvalue analysis
- Visualization: Interactive 2D + 3D Plotly environments
- Rendering: Manim cinematic orbital animation
- Interaction: Live mass, separation and perturbation controls
celestia/
│
├── app.py
├── physics.py
├── rebound_sim.py
├── frames.py
├── viz.py
├── manim_viz.py
├── requirements.txt
├── logo.png
└── README.md
Celestia was developed for:
as a submission for the Cosmic Code Hackathon 2026.
The project combines software engineering, numerical simulation, astronomy, orbital mechanics and scientific visualization into a single interactive laboratory.
