Package: orbital-sim
orbital-simA customisable and interactive Python simulation build over PyGame that modelsthe orbits of celestial bodies in 2D spaceusing Newton’s law of universal gravitation!You can choose from several includedpreset arrangementsor create your ownsimulation 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.InstallingDependenciesorbital-sim requires the following:Python 3PygameAstropyAstroqueryUser installationorbital-sim is available as a package on PyPI and so can be easily installed for Python 3 usingpip:$ pip install orbital-simUsageOnce 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 configurationspresets.pycontains 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 right after:PresetDescriptionInnerSolarSystem()The sun, Mercury, Venus, Earth and MarsSolarSystem()The sun, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune and PlutoEarthMoon()Just the Earth and its MoonImporting presetsIn either your Python shell or a new Python file, import a specific preset configuration:fromorbitalsim.presetsimportPresetNameConfiguring the simulationNext, 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 settingss=PresetName()Or manually set any or all of the following parameters:dimensions– a tuple(x, y)of the desired width and heightscale– the number of pixels represented by a distance of 1 AU in the simulationentity_scale– magnification of an entity’s diametersim_rate– the number of days that pass in the simulation for every second in real-lifestart_date– the date to start the simulation from, in formatyyyy-mm-ddfullscreen– a boolean for whether the window should be fullscreen or notTip:go toSetting up a custom simulationto find out more about these parameters.For example:# A preset with all its parameters tweakeds=PresetName(dimensions=(500,700),scale=250,entity_scale=5,sim_rate=3,start_date='2020-07-12'fullscreen=True)Running the simulationOnce the simulation has been instantiated, to create the PyGame window and start the simulation, just call itsstart()function:s.start()Controlling the simulationOnce the simulation starts, there are a number of ways to control and interact with it:Key(s)Action(s)SPACEPause/play simulation↑ ↓ ← ↑Move window view; pan about+/-Zoom in and out respectivelyrReset zoom and position./,Speed up and slow down the simulation respectivelylToggle labels on the entitiesqQuit the simulationSetting up a custom simulationBy 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 simulationFirst, we need to create a blank simulation that we then add stuff to. This is done by creating an instance of theSimulationclass. 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.importorbitalsims=orbitalsim.Simulation()Parameters of theSimulationclass:ParameterDefault valueDescriptiondimensions(800, 800)A tuple of the width and height of the window in pixelsscale-1The number of pixels represented by a distance of 1 AU in the simulation (default of -1: automatically calculated)entity_scale10Magnification of an entity’s diameter for better visibilitysim_rate3The number of days that pass in the simulation for every second in real-lifestart_dateNone=todayThe date to start the simulation from in formatyyyy-mm-dd(note:if left blank, defaults to the current dayfullscreenFalseBoolean for whether the PyGame window is fullscreen or not (note:fullscreen mode overridesdimensionsparameterNote: PyGame will often encounter framerate issues on certain devices like the Retina MacBooks. If you encounter this, settingfullscreen = Truewill help.II. Adding entities using JPL HORIZONSJPL HORIZONS assigns aunique IDto every object in the solar system that it tracks. You can search up entities and find their ID onJPL HORIZON’s web interfaceby 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 theadd_horizons_entityfunction of theSimulationobject we just created. The function takes in two IDs:entity_idis theentity to add,observer_idis thereference pointfrom where the position ofentity_idwill 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 observerto 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 theadd_horizons_entityfunction:ParameterDefault valueDescriptionentity_idrequiredJPL HORIZONS ID of the entity to addobserver_idrequiredJPL HORIZONS ID of the reference point from where the position and velocity ofentity_idis calculated from (ifentity_idandobserver_idare the same, the object will be rendered at the centre of the screen 0,0)massrequiredMassin kgof the entity to add (mass is not provided by JPL HORIZONS, so it has to be added manually)diameter1e-5Diameterin AUof the entity to add (optional – only used for correct rendering of size)III. Adding custom entitiesYou can also add a fully custom entity with the functionadd_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.ParameterDefault valueDescriptionpositionrequiredTuple (x, y) describing the distance inAUfrom the centre of the system (0, 0)massrequiredMass of the entity inkgspeed0Magnitude of initial velocity inAU/dayangle0Angle of initial velocity inradiansdiameter1e-5Diameter of the entity inAUe0(if applicable) Eccentricity of the orbit from0-1aNone(if applicable) Semi-major axis of the orbit inAUname''A string for the entity's label nameIV. Running the simulationOnce everything has been setup, call thestartfunction 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!