Stableorbit

  A Distributed Solar System Generator And 3D Viewer

Collin Schroeder



2009/04/20

INTRODUCTION

Stableorbit is a collection of programs used for generating and simulating solar systems. The most recent additions to the collection have been a client and a server (solarClient and solarServer). The client is 3D visualisation used for evaluating and viewing systems downloaded from the server. The server provides clients with the ability to retrieve previously generated systems and save newly generated ones. Both solarClient and solarServer work together as a distributed solar system generator and viewer.

History

http://code.google.com/p/stableorbit/wiki/History

Stableorbit started out as two programs, a Genetic Algorithm and a 3D solar system visualiser (named 'GA' and 'planetarium' respectively). The Genetic Algorithm uses stochastic methods to find long lasting (stable) solar system configurations. Through repeated mutations and simulations GA pushes a population of solar systems, each containing one or more stars and multiple planets towards long-term stability. The planetary systems can then be displayed in 3D using our planetarium tool.

GA and planetarium were excellent candidates for creating a distributed GA that doubled as a screen saver. By offloading the CPU-intensive fitness evaluation to the client (running planetarium as the screen saver) we were able to vastly increase the number of systems generated simultaneously simply by connecting more clients.

Although operational, further modifications were needed before we started to generate systems with both good stability ratings as well as elliptical orbits. More of this is described later.


Physics & AI Concepts

http://code.google.com/p/stableorbit/wiki/PhysicsAI


Stableorbit didn't always produce pretty elliptical orbits. The searching algorithm required a great deal of tuning before the desired results were achieved. Ryan Haynes contributed most of the physics code and mathematical backing for the project. This section includes his descriptions of the physics algorithm as well as my description of the search algorithm.

 

"Stableorbit utilizes an O(N^2) Leapfrog Euler Algorithm for numerical integration. Using the leapfrog method we may make our time step larger while conserving the total energy of the system."

- Ryan Haynes (co-developer)


The derivation of the leapfrog method can be found here:

http://stableorbit.googlecode.com/files/SO-Physics.pdf

 


A solar system's stability (or fitness) is determined inside 'orbitSystem.py' using the Virial Theorem. The Virial Theorem provides us with a numerical representation of the ratio between potential and kinetic energy. A value between 0.3 and 1 indicates a potentially stable system. Because elliptical orbits cause planets to speed up and slow down (yielding different Virial ratios) the VT scores must be averaged over time.

The GA initially focused on trying to create multi-planet and multi-star systems. We had a difficult time creating anything that resembled an orbit. Even after evaluating systems over extremely large time period (searching for VT averages of about 0.5) we couldn't find any orbits. Later on I determined the root of the problem. Our systems were being generated with multiple stars and about fifteen planets, the masses of the additional star or stars were throwing off the Viral Theorem and causing the planets to become insignificant in terms of the VT. This left us with stable binary systems of two or more stars orbiting each other and numerous planets flying out into space. Restricting the starting conditions to one star and one planet enabled orbits to be found using a simple random search without the need for a Genetic Algorithm.

More info on the Virial Theorem can be found here:

http://en.wikipedia.org/wiki/Virial_theorem



Dependency Links and Descriptions

http://code.google.com/p/stableorbit/wiki/Dependencies


StableOrbit is built on Python2.5 and uses the Panda3d engine for visualisation. This ensures cross platform compatibility for Windows, Macintosh, and Linux. Other dependencies are required for the files in the beta folder but are currently under development and beyond the scope of this document.


Python is available for Windows and Mac users here:

http://www.python.org/download/

Ubuntu and other Debian based Linux distributions should retrieve it through their package manager or by the following command:

sudo apt-get install python2.5

Panda3d can be downloaded for all platforms over here:


         http://www.panda3d.org/download.php


A Subversion client is recommended but not necessary. Windows users can get one here:

http://tortoisesvn.net/downloads

Debian based Linux distributions can retrieve it through:

sudo apt-get install subversionb

Mac users can download this subversion installer:

http://www.codingmonkeys.de/mbo/

The StableOrbit source code can be used for all Operating Systems. Non-Subversion users can get a zip containing the files here:

http://stableorbit.googlecode.com/files/stableorbit.zip

Command-line Subversion users can get it using the following command:

svn checkout http://stableorbit.googlecode.com/svn/trunk/ stableorbit-read-only

User Manual

http://code.google.com/p/stableorbit/wiki/Manual?ts=1241520104&updated=Manual

Launching the Client
Once Python and Panda3D are installed, and stableorbit is extracted to a location of your choosing. Open the folder containing stableorbit either through a file-browser or command-line. once there You can launch the client by double-clicking 'solarClient.bat' in Windows or typing 'python solarClient.py' from the command line.

A black window should launch. It will remain black for a few seconds while the client attepts to connect to the server and either retrieves a series of systems from the server or generates it's own if a connection problem is encountered. During this period the text in the console describes the status of the client and will look something like this:

cos@chunk:~/stableorbit$ python solarClient.py
DirectStart: Starting the game.
Known pipe types:
  glxGraphicsPipe
(all display modules loaded.)
connecting to server http://bamdastard.kicks-ass.net:8000
connection acquired
retrieving a system
converting xfile
launching evaluator
calculating score
system stability score =
2.62619423771
retrieving a system
converting xfile
launching evaluator
calculating score
system stability score =
5.85486589733

This will continue until a system with a stability below 1.0  is found. The text in the console will state 'found acceptable system, recording system as: '. The next line reveals the  system name recorded by the server, this can be used to retrieve and view the system later. An example of the console output is shown below:

system stability score =
0.999404387469
found acceptable system, recording system as:
system15.sys
launching planetarium.. .  .    .        .

Afterwards the stars will load into the black window and you'll know the client has received or generated an acceptable system.



The system is now loaded but we are too close to see it. Hold the right-mouse button and push your mouse slowly up to zoom out.  A picture like this should emerge:

Client Navigation

 The mouse is used to change views while using the client.


Client Configuration

The Client was designed to be a passive screensaver.  With this in mind I decided alternate functionality should be achived by launching the solarClient class with different arguments. To change these runtime arguments open solarClient.py in a text editor and scroll to the bottom.
 
#Uncomment the following line to retrieve "system6" from the server
#defaultClient = solarClient('http://bamdastard.kicks-ass.net:8000', 1, "system10.sys")

#Uncomment the following line if you want the client to run offline
#defaultClient = solarClient("standalone",1, "none")

#this is the default configuration which attempts to retrieve a system from
#the server. Failure will cause the client to launch locally in disconnected mode
defaultClient = solarClient()

The first comment block above is an example which retrieves "system10.sys" from the server and launches it using the planetarium. Example client console output is pictured below:

connecting to server
http://bamdastard.kicks-ass.net:8000
attempting to retrieve and launch system:
system10.sys
unpacking system
launching evaluator
calculating score
system stability score =
0.997394952702
launching planetarium.. .  .    .        .

The Second comment block shows how to launch the client in disconnected mode.

Server Configuration

If you wish to run your own SolarServer.py you can do so by simply changing the IP address located at the bottom of 'solarServer.py' to reflect your IP address. The client then must also be launched with the same IP address as an argument.

 Troubleshooting

  It's common for windows users to encounter the following error:
simply launch the 'solarClient.bat' instead of 'solarClient.py' or alternatively, using te console try using  the following command from within the stableorbit directory:
     'python solarClient.py'

Previously Existing Architecture

What follows is a description of the state of stableorbit before the building solarClient and solarServer.

Fragmentation of Concerns

Stable Orbit contains two programs; a genetic algorithm for simulating and evolving a population of systems, and a three-dimensional solar system simulation viewer. Each works independently  but share the underlying simulation and solar-system class structure.

The Genetic Algorithm 'GA.py'

Class Diagram:

    GA.py is composed of seven classes. The Body class is composed of three vector classes (Velocity and Acceleration and Position).
    The System class  contains many important methods the GA uses. System is composed of a set of bodies and the methods commonly applied against them. It can randomly generate itself  and mutate and run a basic evaluation test for net kinetic energy/ potential energy called the (Viral Therom).
    The Eval class takes a System and an integer representing the number of timesteps to run, and returns the fitness after running the System through the timesteps. 
    GeneticAlgorithm takes the population size as a parameter then repetedly mutates and runs each System through the Eval class. If  the mutated system performs better than the original, the original is tossed out, otherwise the original is mutated and evaluated again. the process is repeted until all systems pass the predefined time-step requirement. Each system and generation is written out to a folder for viewing later.    

The Viewer 'Planetarium.py'

Class Diagram:


Planetarium.py is quite simple due to the handy python scripting API that Panda3D offers. The Universe class loads up a System from a text file, then scales and applies textures to each planet based on it's mass. It then enters a loop where it performs the simulation for an infinite number of timesteps.

Re-factored Architecture Plan and Implementation

SolarClient Class Diagram:

Planetarium was expanded to include the Eval and the system classes. The current version has EvalClient and Simulation classes combined in the Eval class. The Universe class is contained inside of planetarium.py.

Operating Sequence
 SolarClient Attepts to connect to the server at "http://bamdastard.kicks-ass.net:8000". Once a connection is established it retrieves system after system from the server evaluating each one until an acceptable fitness is reached.   The client then the system back to the server to record it. Each time a system is saved the recorded name is printed on the clients machine for retrieval from the server.

SolarServer Class Diagram:


  The server version did not end up including a database or Eval class. Persistance is achieved by writing systems out to files on the disk.  The Eval functionality is contained client-side. SolarServer simply awaits clients to connect attempting one of three functions.
GetSystem() returns a randomly generated system to the client which has not yet been evaluated. InsertSystem(xfile) records the system stored in xfile and returns the name it was saved under. RetrieveSystem(sysName) does exactly that by attempting to retrieve a system from the server under