Galaxy2 User Guide

Contents - click on topic below
   \>Introduction\>             Short Description
   \>License and Warranty\>  
   \>Origin and Contact\>    
   \>Galaxy2 Operation\>        How to use Galaxy2
   \>Technical Notes\>

Introduction
   Galaxy2 is a free Linux computer program which simulates the motion of stars under the 
   influence of gravity. Create a random field of stars to begin with, then watch the 
   stars move as they are accelerated by their mutual gravitational attractions. You may 
   vary the number of stars and the strength of the attractive force between them. Observe 
   how the attractive forces accelerate individual stars and send them careening in new 
   directions. Large groups of stars develop into patterns over time: clusters and spiral 
   arms. Galaxy2 could serve as a learning aid for young students of science.

License and Warranty
   Galaxy2 is licensed under the GNU General Public License v3 (Free Software Foundation). 
   Galaxy2 is not warranted for any purpose whatsoever.

Origin and Contact
   Galaxy2 originates from the author's web site: \_https://kornelix.net
   Other web sites may offer it for download. Modifications may have been made.
   If you have questions, suggestions or a bug to report: mkornelix@gmail.com

Galaxy2 Operation
   When the program is started, you will see a black window and some buttons on the top.
   +image: galaxy2-8K.jpg

   +image: god.png
   God
   Determine all parameters of the galaxy

   +image: initialize.png
   Initialize
   Populate the galaxy with a random set of stars

   +image: run.png
   Start Time
   Put the stars into motion

   +image: pause.png
   Stop Time
   Stop the stellar motion

   +image: quit.png
   Quit
   Exit the galaxy2 program

   +image: help.png
   Help
   Dispaly the user guide (this document)

   Press Initialize, then Start. Watch for a while to get a feel for what is happening. 

   The [God] button allows you to redesign your galaxy using the dialog on the right. 
   Change the parameters as desired and press [done] to apply the new values. The [open] 
   and [save] buttons load the parameters from a file or save them to a file. Several 
   files are provided as examples. The table below gives some guidance about parameter 
   values, and the technical notes give more detail about how Galaxy2 works and how the 
   parameters influence the results.

Parameter Table

   Name and Range                  Explanation

   parallel execution threads      Parallel threads used for calculations (< CPU cores)
      1 - 8

   number of stars                 Values over 20K are very slow
      10 - 50K 

   star pixel diameter             Star image pixel size: 1x1 or 2x2 or 3x3
      1 - 3

   strength of gravity             Attractive force. Use values >1000 for a few stars, 
      0.1 - 10K                    and values <10 for thousands of stars.

   flat G force distance           Value added to the distance between stars before the 
      5 - 100                      attractive force is calculated. See technical notes

   black hole equivalent stars     Mass of central black hole - number of stars
      0 - 10K

   black hole capture distance     Stars < this distance are eaten by the black hole
      1 - 100

   mean rotational velocity        1.0 is the equilibrium value. Values <1 will cause 
      0.7 - 1.10                   contraction, and values >1 will cause expansion

Technical Notes
    
   \bCalculations
   The attractive force between each pair of stars is calculated using Isaac Newton's 
   formula first published in 1684:  F = G m1 m2 / R2
   For each star, the program computes this attractive force from every other star, and 
   adds them together to compute the total force and acceleration. Each pair of stars 
   requires about 20 calculations. For 1000 stars (1 million pairs), about 20 million 
   calculations are needed to compute all the accelerations one time (one update cycle). 
   These calculations are repeated continuously as the stars move and the attractive 
   forces change. Each star's velocity is updated from it's acceleration, and it's 
   position is updated from it's velocity.

   \bThreads
   There are two main execution threads. Thread 0 updates star velocities and positions 
   and updates the display, once per interval. Thread 1 computes the acceleration of each 
   star, once per interval. If the number of stars is large (1000+), the interval for 
   thread 1 increases because of the computation time required. You can see this in the 
   CPS (cycles per second) number shown in the lower-right corner of the window: this is 
   the rate at which accelerations are recalculated for all stars. You can use the 
   "thread count" parameter to create multiple instances of thread 1, which share the 
   calculation burden. If you have a computer with multiple CPUs (cores), increasing this 
   number enables you to run larger models at higher speed and accuracy. Note that the 
   star velocity on the screen is not increased, only the rate that accelerations are 
   recalculated is increased, and therefore the accuracy of the model. Use one thread if 
   your computer has 1 or 2 processors. Use 3 threads if you have 4 processors. Keeping 
   one processor available for running the screen updates results in smoother motion.

   \bCPS
   The update cycles per second is displayed in the lower right corner. For a small 
   number of stars (<200), CPS is dominated by the sleep interval of 0.02 seconds per 
   cycle (compile time constant). For a large number (1000+) CPS is dominated by the 
   processing time required to calculate all the accelerations.

   \bStar Replacement
   Stars that move off-screen are replaced with new stars distributed randomly. 
   The same goes for stars falling into the black hole.

   \bBlack Hole
   This parameter allows you to put a black hole with some large mass at the center of 
   the galaxy. Stars coming within the capture distance are devoured and re-created 
   somewhere else. The capture distance is in units, where the entire simulation space 
   is 1000 x 1000 units.

   \bR flatband
   This parameter is added to the distance between each pair of stars for calculating 
   their attractive force. It has the effect of reducing the forces between nearby stars 
   and allowing them to be more influenced by the greater number of distant stars. If 
   flatband is very small (10 units or less), stars will accelerate each-other strongly 
   when they get close together. If you run a model with thousands of stars, and you see 
   many local collapses taking place, increasing this parameter will reduce this effect.

   \bInitial Velocity
   When a model with a large number of stars is initialized, the force on each star will 
   be mainly pulling to the middle, since the initial distribution of stars is symmetric 
   and the black hole is in the middle. The initial velocity assigned to each star is 
   calculated to balance this force - the centrifugal force will be equal and opposite, 
   and the stars will tend to rotate around the middle without expanding or collapsing 
   inward. This condition will persist until the stars undergo regional collapses and the 
   symmetry breaks down. The parameter allows you to bias the initial velocity to make 
   the stars tend to fall inward (values < 1) or expand outward (values > 1). A slight 
   bias to fall inward (e.g. 0.95) seems to give good results.

   \bSpeed vs Precision
   The speed of galactic evolution can be accelerated by using higher values for gravity 
   and/or a bigger black hole. This will result in higher initial angular velocities to 
   balance the greater pull to the center, and the whole system will evolve faster. This 
   reduces precision, since the stars will move greater distances between recalculation 
   of acceleration. Less precision results in more chaos and less interesting patterns. 
   For good precision, the stars should not move more than a few pixels per update cycle 
   (see CPS above).

   \bAngle of View
   Internally, the simulation takes place in a square region, which is projected on the 
   rectangular display window. If you make the window wide in comparison to its height, 
   it is the same as viewing the galaxy from an oblique angle.

   \b2-body and 3-body problem
   When two stars are simulated, a stable orbital pattern of rotation can persist for a 
   long time (not forever, due to computational imprecision). When three or more stars 
   are simulated, various orbital patterns come and go with varying degrees of stability. 
   This "three-body problem" has no analytic solution and is chaotic. The semi-persistent 
   recurring patterns that may be seen are called “strange attractors” in chaos theory.

   \bPixels
   If the pixel parameter is 1, only one pixel is used to display a star's position, and 
   the motion is "jerky" (movement is one pixel at a time). If the parameter is 2 or 3, 
   a 2x2 or 3x3 group of pixels is used, and the motion is made smoother by anti-aliasing 
   the pixels: star position is calculated to the nearest 0.1 pixel, and shades of gray 
   are used to make it appear as though the motion is finer than one pixel.
   
   +image: anti-alias.jpg
   3x3 star, moving up      time → 
    
   \bUninstall
   Debian package: use command: sudo apt remove galaxy2
   Tarball: use command: sudo make uninstall
   Binary package: delete 'galaxy2' files in $HOME/.local/* 


