orbital-sim

A customisable and interactive Python simulation build over PyGame that models the orbits of celestial bodies in 2D space using Newton’s law of universal gravitation!

You can choose from several included preset arrangements or create your own simulation configuration from scratch!

Precise positioning and movement vectors are obtained through built-in access to JPL’s HORIZONS system, a resource that provides precise data for objects in our solar system.

Installing

Dependencies

orbital-sim requires the following:

• Python 3
• Pygame
• Astropy
• Astroquery

User installation

orbital-sim is available as a package on PyPI and so can be easily installed for Python 3 using pip:

$ pip install orbital-sim

Usage

Once you have the package installed, you’re good to go! From here, you can either try out one of the preset configurations that come with the module, or you can delve into creating your own orbital simulation! Details for both of these are explained below.

Preset configurations

presets.py contains a number of orbital systems with all the celestial bodies already specified, so all that needs to be done is to import it, configure the simulation and get it running.

The following are the available presets and the bodies that are included in them – details to using them are in the next section:

Importing presets

In either your Python shell or a new Python file, import a specific preset configuration from the module:

from orbitalsim.presets import PresetName

Configuring the simulation

Next, instantiate the preset simulation and pass through any parameters if you wish to do so. You can choose to leave everything to its default value by not including anything in the parentheses:

# A preset with default settings
s = PresetName()

Or manually set any or all of the following parameters:

• dimensions – a tuple (x, y) of the desired width and height
• scale – the number of pixels represented by a distance of 1 AU in the simulation
• entity_scale – magnification of an entity’s diameter
• sim_rate – the number of days that pass in the simulation for every second in real-life
• start_date – the date to start the simulation from, in format yyyy-mm-dd
• fullscreen – a boolean for whether the window should be fullscreen or not

Tip: go to Setting up a custom simulation section to find out more about these parameters.

For example:

# A preset with all its parameters tweaked
s = PresetName(
    dimensions = (500, 700),
    scale = 250,
    entity_scale = 5,
    sim_rate = 3,
    start_date = '2020-07-12'
    fullscreen = True
)

Running the simulation

Once the simulation has been instantiated, to create the PyGame window and start the simulation, just call its start() function:

s.start()

Controlling the simulation

Once the simulation starts, there are a number of ways to control and interact with it:

Setting up a custom simulation

By setting up a custom simulation, you have control over exactly what entities to add and where. You can either select existing entities in our solar system through JPL HORIZONS or create entities with custom details and characteristics.

The next few sections will detail how you may go about getting a custom simulation up and running using orbital-sim.

I. Instantiate simulation

First, we need to create a blank simulation that we then add stuff to. This is done by creating an instance of the Simulation class. Just like with the preset configurations, you can use the default parameters by not specifying them, or change certain ones to taste, up to you.

import orbitalsim
s = orbitalsim.Simulation()

Parameters of the Simulation class:

Note: PyGame will often encounter framerate issues on certain devices like the Retina MacBooks. If you encounter this, setting fullscreen = True will help.

II. Adding entities using JPL HORIZONS

JPL HORIZONS assigns a unique ID to every object in the solar system that it tracks. You can search up entities and find their ID on JPL HORIZON’s web interface by looking up a target body by keyword. (While it is possible to refer to objects by name, this can sometimes be ambiguous due to multiple object names containing the same word)

To add an entity that exists in the JPL HORIZONS system to the simulation, we’ll use the add_horizons_entity function of the Simulation object we just created. The function takes in two IDs: entity_id is the entity to add, observer_id is the reference point from where the position of entity_id will be calculated relative to.

Important: when generating the simulation, all entity positions are calculated from the centre of the screen (0, 0). Therefore, it is recommended that entities are added in relation to the same observer to ensure the distances aren’t off.

For example, the following snippet adds the entity with an ID of 3 (which happens to be Earth), with its distance calculated in relation to the sun (approximately 1 AU by definition).

s.add_horizons_entity(
    entity_id = '3',
    observer_id = 'sun',
    mass = 6e24,
    diameter = 8.5e-5
)

Parameters to the add_horizons_entity function:

III. Adding custom entities

You can also add a fully custom entity with the function add_custom_entity. With this function, you give the entity its position, movement vectors and physical characteristics.

s.add_custom_entity(
    position = (1, -0.5),
    mass = 2e24,
    speed = 0.2,
    angle = 3/2 * math.pi,
    name = 'some planet'
)

Some parameters are optional but some are required. See the table below for more information.

IV. Running the simulation

Once everything has been setup, call the start function of the simulation object to begin the simulation.

s.start()

That's it! That's all there is to getting a custom simulation up and running!