Groho is a simulator for space flight, communication and warfare within the solar system.
Space is unimaginably vast. My goal is to create a simulator that will give us an appreciation of just how lonely even our tiny corner of the universe is. We define a solar system model (the Orrery - based on NASA's planetary data), set up space craft scripts (Flight Plans), and then sit back and watch the action unfold. The program makes it easy to setup, run, save, modify, inspect and compose (combine together) simulations.
My hope is that we will come away with an understanding of basic orbital manuevers, an intuition of the time delays in communicating and coordinating across the solar system and a feel for what life will be like for our descendants who set sail away from the home planet.
Groho (গ্রহ) is the Bengali word for planet. Grohomondol (গ্রহমণ্ডল) is the word for planetary system but is more of a mouthful.
cd examples/001.basics
../../release_build/groho scn.groho.txt
cd examples/002.full-solar-system
../../release_build/groho scn.groho.txt
- Features and use cases
- Compilation/building
- Dependencies
- [Magnum/Corrade](#magnumcorrademagnum)
- Compile
- Dependencies
- Manual/Tutorial
- Physics/astronautics word salad
- Related software
- Thanks
- Meta: Why did you put everything in this one document?
This simulator is designed to help gain intuitions of how near-future space flight within the solar system would look like. To this end it allows us to:
- Simulate the flights and interactions of hundreds of spacecraft
- Simulate decades long journeys in reasonable CPU time.
- Compose multiple journeys together to make a complex simulation from simpler ones
- Perform reproducible simulations (seeded random number generators, stable numerical calculations)
- Compare multiple versions of a simulation
The simulation works by setting up a scenario and then letting everything evolve according to physical law and scripted events. The experimenter influences the simulation only through the choice of scenario and script parameters.
The motions of planets, moons and larger asteroids are taken from existing ephemeris and are not propagated via n-body gravitational simulations. The expected time scales of the simulations (upto a century) are short enough that existing ephemeres will do fine and will save us a lot of computation. The gravitational effect of each planet, moon and asteroid on a ship is taken into account.
Communications over solar-system distances are interestingly affected by the finite speed of light. The simulation enables the calculation of when an event at one location is detected at other locations/ships.
This code requires a C++17 compiler. In case you need it, there is a Dockerfile that installs a recent GCC. I used the following creature comforts from C++17
std::optional- structured bindings
- typename in a template template parameter
[[maybe_unused]]attribute
You should follow the instructions on the Magnum project page, but in brief:
For macOS:
- For the base:
brew install mosra/magnum/magnumandbrew install mosra/magnum/corrade - For the plugins (required for text rendering):
brew install mosra/magnum/magnum-plugins
git clone git@github.com:kghose/groho.git
cd groho && \
mkdir build && \
cd build && \
cmake -DCMAKE_BUILD_TYPE=Release .. && \
make
groho --help # Get help about the program
groho --actions # List available spacecraft actions
Groho simulates the solar system using data produced by NASA/JPL. This data
is distributed by NASA as planetary kernels found here.
There is a script under the examples directory that
I used to pull in all the .bsp files for the solar system. Be aware that
this is a few GB worth of data. You are free to use whatever kernels you wish.
I save all these kernels under the examples directory.
Groho uses a scenario file, one or more flight plans and one or more
annotation files to run a simulation and organize information on screen.
Simulation files can be edited with your favorite editor and versioned with
your favourite versioning system. groho is independent of all this. What
groho does is monitor changes to the simulation files on the file system and
updates the simulation computations when the files change.
In the examples directory are a series of tutorials-by-example.
Each directory contains a scenario file, flight plans and annotation files
with a mixture of commentary and code to show you the syntax.
Start with the basic example: Read the simulation file, flight plan file (there are two) and the annotation file.
After that, just browse the examples to get a feel for what else is available.
Flight Plan actions are commands to a ship to do something. Actions can take place at a particular time or be triggered by a particular world state. Actions happen in sequence.
A flight plan can create signals on behalf of a ship. Signals travel radially out at the speed of light from their point of origin and can be recieved by other ships once they are within the sphere. Once the signal has spread past the furthest simulation object it is removed, since all ships have recieved the signal by that time. Signals can be shaped, such that they have different amplitudes in different directions. Ship recievers can have different sensitivities to signal intensity.
Restarts allow
- An existing complete simulation to be rerun with an extended end time without having to recompute the previously computed segment
- An existing simulation to be rerun intelligently conserving previously computed parts.
Restarts are have not been implemented yet but features are implemented with restarts in mind.
We assume that every ship has access to perfect knowledge about all Orrery objects. Every ship has access to perfect information about itself, but not others. In order to get information about other ships it has to make use of signals (which travel at the speed of light). Signals can be radar/lidar which allow ranging, velocity and some identity information or data packets broadcast from another ship, which can carry arbitrary information.
Dragging the mouse will orbit the camera. Scrolling will zoom in and out. Pressing ALT while scrolling will move back and forth in time. The up/down cursor keys cycle through the planets/asteroids/spacecraft and the left/right keys cycle through the satellites of said planets allowing us to center the camera on different objects.
Pressing p will toggle display of body paths, m will toggle display of the
fixed size markers, b will toggle display of the scaled circles that
represent the actual size of the bodies, and o will toggle the information
overlay.
Once you have sufficient objects in the simulation, it becomes hard to find things.
Whatever view you can get to using the mouse/keyboard, you can also get to using
the view annotation and in a much more effective way. Check out the documentation.
Eventually the tutorial here will be copied over into this space.
I personally learn well by example, so I wanted to try this out. I also use these tutorial scripts as ways to prototype proposed simulation file syntax, to see how it could look and work.
Lastly, for a hobby project, it's a wasteful duplication of effort to have to create/update example scripts and a separate manual or tutorial (where I'd have to paste in snippets of code anyway). I chose to use comments in the simulation files as a reliable way to keep upto-date documentation.
I'm aspirational. But seriously, I use the manual and the example input files as functional specifications. As I build out more of the software, more of the specifications are implemented. Please file bug reports as necessary.
There is a bunch of interesting physics and math behind orbital maneuvers. From Robert A. Braeunig's page we have the following named maneuvers:
- Hohmann transfer orbit
- One-Tangent Burn
- Spiral transfer
- Simple plane change
And, from poliastro
- Lambert’s problem
- Bi-elliptic transfer
NASA's GMAT software (github) is probably the be-all and end-all of spacecraft simulation. It would probably have sufficed for my needs but I like to program computers and learn math, so I stubbornly rolled my own to my own (much more limited) specifications.
"SSVG is simulation software which enables users to fly their own space probes in the solar system. Each space probe has three propulsion systems: a chemical propulsion engine, an electric propulsion engine, and solar sail. Fly your own space probe in the precisely simulated Solar System."
I found SSVG on Oct 14th and browsing through the manual]SSVG-manual found that the author had a very similar concept (including the name "Flight plan") and a cool looking GUI for writing flight plans! I had, by then, however, discarded the idea of timed actions in favor of event/condition driven actions. But it is cool for me to see a "flight plan" like concept, because I have so far been unsuccessful in finding what a real flight plan, or set of propulsive maneuvers actually looks like.
I ran into the Trajectory Browser while looking for what interplanetary mission programs look like. It's awesome. However
All trajectories are pre-computed and stored in a database that contains all the solutions. In order to compute new trajectories to a non-existing object and/or if you wish to add a particular object that is not currently available, please contact us and we will have it included.
REBOUND is an N-body integrator. Groho completely punts on this aspect of the simulation and relies on the NASA/JPL ephemeris kernels (which in turn are products of a constrained N-body simulation). The REBOUND code is a good place to explore different integrators and the rebound paper is a good place to readup about Symplectic integration. If you are into that kind of thing.
I've used Orbiter since 2001 or so. It was my main instrument of thesis procrastination. It's very detailed and visually rich and a blast to play. It's an interactive simulation where you fly space craft with your keyboard and mouse. It's closed source and its internals are a little opaque. For example, I do not know what orrery model it uses or if it does an n-body simulation, if it has accurate models for the axial tilt of the planets and moons or these are just arbitrary and so on.
Bussard is a cool hacking/spaceflight game where you write complex programs to fly your spaceship to solve puzzles.
SolarSystemOrbiter - "Plot the orbits of the planets in our Solar System and calculate the Hohmann Transfer Orbits to transfer your rocket ship from one planet to the other and back."
poliastro is an open source collection of Python subroutines for solving problems in Astrodynamics and Orbital Mechanics.
Celestia - "A real-time space simulation that lets you experience our universe in three dimensions."
asterank - "Using publicly available data and scientific papers, the project evaluates the economic prospects of mining nearly 600,000 cataloged asteroids." They are live at http://www.asterank.com/.
Included in the code are the following fine pieces of software
- loguru from Emil Ernerfeldt for the logging
- CLI11 from Henry Schreiner for the CLI
- catch(2) from Phil Nash for unit tests
- magnum/corrade from Mosra (Vladimír Vondruš) for everything graphical
I was helped in writing the code by
- The Clang compiler and
clang-format - Visual Studio Code from microsoft which does everything I want in a code editor (Though the debugger integration needs some work.)
- Instruments. I dislike Xcode, but love Instruments
- markdown-toc from Alan Walk. I used that to generate the table of contents in markdown documents, which allowed me to consolidate my documentation.
When I started the project I had text documents all over the place. It seemed like a good idea - one document for an idea or topic. Pretty soon I had multiple docments with similar ideas/topics and I began to forget that I had them. Discoverability began to be a problem. So I decided to try packing stuff into as few documents as possible. You don't have to read all this at once, you can look for things using your browser or text editor's search function and not have to keep jumping from document to document. I will try to use bookmarks to help orientation. It's an experiment - tell me if you hate it.
That said, there is a separate file, which contains some war stories about C++ and implementation.