.TH GALAXY 1
.SH NAME
galaxy, mkgalaxy \- galactic n-body simulator
.SH SYNOPSIS
.B games/galaxy
[
.I options
] [
.B -i
] [
.I file
]
.br
.B games/mkgalaxy
[
.I options
] [
.B -i
] [
.B -f
.I file
]
.I size
.SH DESCRIPTION
.I Galaxy
is an n-body simulator that uses a Barnes-Hut quad-tree
to calculate gravitational interactions.
Typical usage is to read a galaxy file (see
.IR galaxy (6))
from standard input
using the
.B -i
command-line option or from a
.I file
using the
.B -f
option. If no file is read then the simulator starts with an empty
universe.
.SS Mouse commands
.PP
New planetary bodies can be created with mouse button 1.
Holding button 1 will reposition the body.
Holding a button 1-2 chord changes the mass/size
of the body. Holding a button 1-3 chord
changes the initial velocity of the body. Releasing button 1
restarts the simulator with the new body in motion. When new
bodies are created, the simulator maintains the Galilean (inertial)
reference frame.
.PP
Mouse button 3 opens a menu with the following options:
.TP
.B move
Change the visible region of the simulation
by holding button 1 and dragging. Any other mouse
button restarts the simulation.
.TP
.B zoom
Prompts for a floating point value to change the scale of the
simulation. E.g. a value of 2 will halve the scale (zoom in)
and a value of 0.5 will double the scale (zoom out).
.TP
.B speed
Prompts for a floating point value to change the speed of
the simulation. E.g. a value of 2 will double the speed
of the simulation and a value of 0.5 will
halve the speed. Accuracy is sacrificed for greater speed.
.TP
.B gravity
Prompts for a floating point value to change the gravitational
constant. E.g. a value of 2 will double the force exerted by
gravity and a value of 0.5 will halve it.
.TP
.B save
Prompts for a file name to save the current galaxy as a
.IR galaxy (6)
file.
.TP
.B load
Prompts for a file name to load the galaxy from the
.IR galaxy (6)
file.
.TP
.B exit
Exits the simulator.
.SS Keyboard commands
The following keys are recognized as commands:
.TP
.B a
Show accelerations as vectors.
.TP
.B v
Show velocities as vectors.
.TP
.B s
Show statistics such as the number of bodies being
simulated, the maximum depth of the quad-tree, and the
average number of calculations made per body.
.TP
.B q
Exit the simulator.
.TP
.B space
Pause and unpause the simulator.
.TP
.B del
Exit the simulator.
.SS Command-line options
Certain aspects of the galaxy simulator are controlled by
the following options:
.TP
.BI -t " throttle"
Causes the process that calculates forces to relinquish
the processor for
.I throttle
milliseconds after each calculation.
.TP
.BI -G " gravity"
Sets the gravitational constant to
.I gravity.
The default value is 1.
.TP
.BI -ε " softening"
Sets the
.I softening
factor to prevent gravitational singularities during
collisions or near-collisions. The default value is 500.
.TP
.BI -f " file"
Reads the galaxy file
.I file
(see
.IR galaxy (6)).
.TP
.B -i
Reads a galaxy file from standard input.
.SS Mkgalaxy
.I Mkgalaxy
is a utility to create galaxies for simulation.
Galaxies can be assembled incrementally by reading an
existing galaxy file from standard input with the
.B -i
command-line option or from a
.I file
with the
.B -f
option. Mkgalaxy then writes to standard output a
.IR galaxy (6)
file with a galaxy of the given
.I size
together with the previously read galaxy.
Galaxies generated by mkgalaxy have characteristics
determined by the following options:
.TP
.BI -d " distance"
.I Distance
determines the spacing between bodies.
The default value is 100.
.TP
.BI -s " size"
Bodies have the given
.IR size .
The default value is 25.
.TP
.BI -v " velocity"
Bodies have the given
.I velocity
in a random direction.
The default value is 0.
.TP
.BI -av " angular velocity"
Bodies have the given
.I "angular velocity"
relative to the center of mass of the new galaxy being generated.
The default value is 0.
.TP
.BI -gv " x,y"
The entire galaxy being generated is given the directional velocity determined
by the vector
.RI ( x,y ).
The default value is (0, 0).
.TP
.BI -o " x,y"
The entire galaxy being generated is offset by the vector
.RI ( x,y ).
The default value is (0, 0).
.TP
.B -sq
The galaxy being generated is a square. Without this option, the galaxy
will be circular.
.PP
The arguments to the
.BR -d ,
.BR -s ,
.BR -v ,
and
.B -av
arguments have the form
.B s
or
.B s±r
where s and r are double-precision floating point numbers.
.B S
is the base value and
.B r
if given determines a range in which the value will vary randomly
from the base.
.SH EXAMPLES
Two rotating circles destroy each other:
.IP
.EX
games/mkgalaxy -av 100 -d 60±50 -v 10 2000 |
games/mkgalaxy -i -av -70 -d 80±50 -v 10 -o 6000,2000 -gv -80,40 3000 |
games/galaxy -i
.EE
.PP
Cool patterns made by a square galaxy:
.IP
.EX
games/mkgalaxy -sq -av 20 5000 | games/galaxy -i
.EE
.SH SOURCE
.B /sys/src/games/galaxy
.SH SEE ALSO
J. Barnes & P. Hut (December 1986). "A hierarchical O(N log N) force-calculation algorithm".
.IR Nature .
324 (4): 446–449.
.PP
.IR galaxy (6)
.SH HISTORY
.I Galaxy
and
.I mkgalaxy
first appeared in 9front (Feb, 2017).