Newtonian N-body gravity simulator accelerated with C library.
- Interactive module: real time interactive N-body simulation
- Plotting module: customize your own system and generating plots
Link: https://alvinng4.github.io/Gravity_Simulator_Web/
Click once after you see the green loading bar showing "Ready to start!". You should then see the main menu. From there, simply select a system to start. See controls for basic controls.
This online demo is built with the pygbag package.
Warning
In Safari, if you accidently selected/clicked the window, the FPS would drops significantly. To fix it, simply click on something else outside the game window.
- Quick Start
- Interactive module
- Plotting module
- Compensated summation
- Available integrators
- Program keeps crashing. What should I do?
- Feedback and Bugs
- Data Sources
- References
- Acknowledgement
This program requires Python version 3.10 or higher.
Download the source files, or clone this repository by running the following command in terminal:
git clone https://github.com/alvinng4/Gravity-Simulator
Install the required packages by
pip install .
Interactive module: navigate to the source directory and then run the following command in terminal
python gravity_sim
Plotting module: navigate to the source directory and then run the following command in terminal
python gravity_plot
If the C libraries cannot be loaded after running the program, you should see the following message in your terminal window
System message: Loading c_lib failed. Running with numpy.
This does not affect the simulation result, but the program may runs 100 times slower.
To fix this, you may need to recompile the library from the src folder.
Once you have downloaded the source files, navigate to the source directory in terminal and run
python gravity_sim [-n|--numpy] [-r|--resolution <width> <height>]
By default, the simulation is performed in C to improve performance. If you want to use numpy, run the program with
python gravity_sim [-n|--numpy]
The default resolution is set to the user's screen size. However, you can set your own resolution by the following command:
python3 gravity_sim [-r|--resolution <width> <height>]
| System | Description |
|---|---|
| Void | Emptiness |
| figure-8 | A "figure-8" orbit involving three stars |
| pyth-3-body | Three stars arranged in a triangle with length ratios of 3, 4, and 5 |
| solar_system | Solar System with the Sun and the planets |
Tip
Pythagorean three body orbit is a highly chaotic orbit with close encounters, which is useful to test the difference between fixed and variable step size integrators. For RK4, the largest dt to produce desired result is 2e-8 days.
| Action | Control |
|---|---|
| Move camera | W A S D/ ↑ ↓ ← → |
| Menu | Esc |
| Pause | P |
| Toggle full-screen mode | F |
| Hide user interface | H |
| Reset parameters | R |
| Create new star | Hold the right mouse button to create a star + drag the mouse to give it an initial boost. |
| Adjust parameter values | Left-click the parameter on the parameters panel + scroll to change its value. |
| Switch integrators | Left-click the integrator on the integrators panel. |
Warning
Switching integrators or changing dt in the middle of simulation may produce some numerical error.
Once you have downloaded the source files, navigate to the source directory in terminal and run
python gravity_plot [-n|--numpy]
By default, the simulation is performed in C to improve performance. If you want to use numpy, run the program with
python gravity_plot [-n|--numpy]
| System | Description |
|---|---|
| circular_binary_orbit | A circular orbit formed by two stars |
| eccentric_binary_orbit | An eccentric orbit formed by two stars |
| 3d_helix | An upward helix consists of three stars |
| sun_earth_moon | The Sun, Earth, and Moon system |
| figure-8 | A "figure-8" orbit involving three stars |
| pyth-3-body* | Three stars arranged in a triangle with length ratios of 3, 4, and 5 |
| solar_system | Solar System with the Sun and the planets |
| solar_system_plus | solar_system with the inclusion of Pluto, Ceres, and Vesta |
| custom | Customize your own system |
Tip
Pythagorean three body orbit is a highly chaotic orbit with close encounters, which is useful to test the difference between fixed and variable step size integrators. For RK4, the largest dt to produce desired result is 2e-8 days.
If you want to setup your own system, choose the "custom" option. Note that the default unit is in solar masses, AU and days.
The system data will be saved once all the required information has been entered. If you wish to make any changes, you can access the file at
gravity_simulator/gravity_plot/customized_systems.csv
The data follow the format
Name, Number of objects, m1, ..., x1, y1, z1, ..., vx1, vy1, vz1, ...
Note: If you have customized system data with the older version, there are "[" and "]" inside the data, which would not work anymore. Please remove them manually.
You may output the trajectory in 2D / 3D as an animation in .gif.
The output file would be stored in gravity_plot/result.
To generate the animation, the program would ask for the following information:
- FPS: Frames per second
- Desired time length of the output file
- File name without extension
- Dots per inch (dpi): the resolution of the output file
- Dynamic axes limit: rescale the axes limit dynamically
- Maintain fixed dt: attempt to maintain fixed step size with variable time step data
If you choose to save the data, the numerical data will be stored in the following folder:
Gravity-Simulator/gravity_plot/results
The file will starts with the metadata which will always follows the same format.
Missing information will be saved as None. Below is an example:
# Data saved on (YYYY-MM-DD): 2024-06-25
# System Name: solar_system
# Integrator: IAS15
# Number of objects: 9
# Simulation time (days): 73048.4378
# dt (days): None
# Tolerance: 1e-09
# Data size: 64596
# Store every nth point: 1
# Run time (s): 1.478802832774818
# masses: 1.0 1.6601208254589484e-07 2.447838287796944e-06 3.0034896154649684e-06 3.2271560829322774e-07 0.0009547919099414248 0.00028588567002459455 4.36624961322212e-05 5.151383772654274e-05
Then, the actual data will be saved in the default unit (solar masses, AU and days), and follow this format:
time, dt, total energy, x1, y1, z1, ... vx1, vy1, vz1, ...
The saved data file can be read by the program. Even if the metadata is corrupted or missing, the program can still read the data file, although some information could be missing.
A method known as compensated summation [1], [4] is implemented in the plotting module.
When we advance our system by
Since
Fixed step size integrators are simple methods to simulate the system with the given step size dt.
| Fixed step size methods |
|---|
| Euler |
| Euler Cromer |
| Fourth Order Runge-Kutta (RK4) |
| Leapfrog |
Embedded RK methods are adaptive methods that decides the step size automatically based on the estimated error. The system would adopt smaller step size for smaller tolerance.
| Embdedded Runge-Kutta methods | Recommended tolerance* |
|---|---|
| Runge–Kutta–Fehlberg 4(5) | 1e-8 to 1e-14 |
| Dormand–Prince method (DOPRI) 5(4) | 1e-8 to 1e-14 |
| Verner's method (DVERK) 6(5) | 1e-8 to 1e-14 |
| Runge–Kutta–Fehlberg 7(8) | 1e-4 to 1e-8 |
IAS15 (Implicit integrator with Adaptive time Stepping, 15th order) is a highly optimized and efficient integrator. It is the default method of the plotting module.
Recommended tolerance*: 1e-9
*For reference only
First, make sure that you are running with python version >= 3.10 and have installed all the required packages. If yes, try running the program with numpy and see if the problem gets fixed. To run with numpy, execute the following command in terminal:
python gravity_sim --numpy
python gravity_plot --numpy
However, note that the program could run about 100 to 1000 times slower with numpy. If the problem persists, please feel free to let me know by opening an issue.
If you find any bugs or want to leave some feedback, please feel free to let me know by sending an email to alvinng324@gmail.com or open an issue.
The solar system positions and velocities data at 1/Jan/2024 are collected from the Horizons System [2]. Gravitational constant, and masses of the solar system objects are calculated using the data from R.S. Park et. al. [3].
- E. Hairer, C. Lubich, and G. Wanner, "Reducing Rounding Errors" in Geometric Numerical Integration: Structure-Preserving Algorithms for Ordinary Differential Equations. Springer, 2004, pp. 272-274.
- Horizons System, Jet Propulsion Laboratory, https://ssd.jpl.nasa.gov/horizons/
- R. S. Park, et al., 2021, “The JPL Planetary and Lunar Ephemerides DE440 and DE441”, https://ssd.jpl.nasa.gov/doc/Park.2021.AJ.DE440.pdf, Astronomical Journal, 161:105.
- H. Rein, and D. S. Spiegel, 2014, "IAS15: A fast, adaptive, high-order integrator for gravitational dynamics, accurate to machine precision over a billion orbits", Monthly Notices of the Royal Astronomical Society 446: 1424–1437.
The integrators in this project were developed with great assistance from the following book:
- J. Roa, et al. Moving Planets Around: An Introduction to N-Body Simulations Applied to Exoplanetary Systems, MIT Press, 2020