sys/man/1/galaxy

   1 .TH GALAXY 1
   2 .SH NAME
   3 galaxy, mkgalaxy \- galactic n-body simulator
   4 .SH SYNOPSIS
   5 .B games/galaxy
   6 [
   7 .I options
   8 ] [
   9 .B -i
  10 ] [
  11 .I file
  12 ]
  13 .br
  14 .B games/mkgalaxy
  15 [
  16 .I options
  17 ] [
  18 .B -i
  19 ] [
  20 .B -f
  21 .I file
  22 ]
  23 .I size
  24 .SH DESCRIPTION
  25 .I Galaxy
  26 is an n-body simulator that uses a Barnes-Hut quad-tree
  27 to calculate gravitational interactions.
  28 Typical usage is to read a galaxy file (see
  29 .IR galaxy (6))
  30 from standard input
  31 using the
  32 .B -i
  33 command-line option or from a
  34 .I file
  35 using the
  36 .B -f
  37 option. If no file is read then the simulator starts with an empty
  38 universe.
  39 .SS Mouse commands
  40 .PP
  41 Holding mouse button 1 while dragging repositions the visible region of
  42 the galaxy. Holding mouse button 2 while dragging up or down zooms the
  43 visible region of the galaxy in or out, respectively.
  44 Mouse button 3 opens a menu with the following options:
  45 .TP
  46 .B "new body"
  47 Creates a new galactic body.
  48 Holding button 1 positions the body.
  49 Holding a button 1-2 chord changes the mass/size
  50 of the body. Holding a button 1-3 chord
  51 changes the initial velocity of the body. Releasing button 1
  52 restarts the simulator with the new body in motion. When new
  53 bodies are created, the simulator maintains the Galilean (inertial)
  54 reference frame where the center of mass of the galaxy is at rest.
  55 .TP
  56 .B speed
  57 Prompts for a floating point value to change the speed of
  58 the simulation. E.g. a value of 2 will double the speed
  59 of the simulation and a value of 0.5 will
  60 halve the speed. Accuracy is sacrificed for greater speed.
  61 .TP
  62 .B gravity
  63 Prompts for a floating point value to change the gravitational
  64 constant. E.g. a value of 2 will double the force exerted by
  65 gravity and a value of 0.5 will halve it.
  66 .TP
  67 .B save
  68 Prompts for a file name to save the current galaxy as a
  69 .IR galaxy (6)
  70 file.
  71 .TP
  72 .B load
  73 Prompts for a file name to load the galaxy from the
  74 .IR galaxy (6)
  75 file.
  76 .TP
  77 .B exit
  78 Exits the simulator.
  79 .SS Keyboard commands
  80 The following keys are recognized as commands:
  81 .TP
  82 .B a
  83 Show accelerations as vectors.
  84 .TP
  85 .B v
  86 Show velocities as vectors.
  87 .TP
  88 .B s
  89 Show statistics such as the number of bodies being
  90 simulated, the maximum depth of the quad-tree, and the
  91 average number of calculations made per body.
  92 .TP
  93 .B q
  94 Exit the simulator.
  95 .TP
  96 .B space
  97 Pause and unpause the simulator.
  98 .TP
  99 .B del
 100 Exit the simulator.
 101 .SS Command-line options
 102 Certain aspects of the galaxy simulator are controlled by
 103 the following options:
 104 .TP
 105 .BI -G " gravity"
 106 Sets the gravitational constant to
 107 .I gravity.
 108 The default value is 1.
 109 .TP
 110 .BI -f " file"
 111 Reads the galaxy file
 112 .I file
 113 (see
 114 .IR galaxy (6)).
 115 .TP
 116 .B -i
 117 Reads a galaxy file from standard input.
 118 .TP
 119 .BI -p " procs"
 120 Specifies the number of extra processes to use in order
 121 to calculate the gravitational force on each body in
 122 parallel.
 123 The default value is
 124 .BR $NPROC-1 .
 125 .TP
 126 .BI -t " throttle"
 127 Causes the process that calculates forces to relinquish
 128 the processor for
 129 .I throttle
 130 milliseconds after each calculation.
 131 .TP
 132 .BI -ε " softening"
 133 Sets the
 134 .I softening
 135 factor to prevent gravitational singularities during
 136 collisions or near-collisions. The default value is 500.
 137 .SS Mkgalaxy
 138 .I Mkgalaxy
 139 is a utility to create galaxies for simulation.
 140 Galaxies can be assembled incrementally by reading an
 141 existing galaxy file from standard input with the
 142 .B -i
 143 command-line option or from a
 144 .I file
 145 with the
 146 .B -f
 147 option. Mkgalaxy then writes to standard output a
 148 .IR galaxy (6)
 149 file with a galaxy of the given
 150 .I size
 151 together with the previously read galaxy.
 152 Galaxies generated by mkgalaxy have characteristics
 153 determined by the following options:
 154 .TP
 155 .BI -d " distance"
 156 .I Distance
 157 determines the spacing between bodies.
 158 The default value is 100.
 159 .TP
 160 .BI -s " size"
 161 Bodies have the given
 162 .IR size .
 163 The default value is 25.
 164 .TP
 165 .BI -v " velocity"
 166 Bodies have the given
 167 .I velocity
 168 in a random direction.
 169 The default value is 0.
 170 .TP
 171 .BI -av " angular velocity"
 172 Bodies have the given
 173 .I "angular velocity"
 174 relative to the center of mass of the new galaxy being generated.
 175 The default value is 0.
 176 .TP
 177 .BI -gv " x,y"
 178 The entire galaxy being generated is given the directional velocity determined
 179 by the vector
 180 .RI ( x,y ).
 181 The default value is (0, 0).
 182 .TP
 183 .BI -o " x,y"
 184 The entire galaxy being generated is offset by the vector
 185 .RI ( x,y ).
 186 The default value is (0, 0).
 187 .TP
 188 .B -sq
 189 The galaxy being generated is a square. Without this option, the galaxy
 190 will be circular.
 191 .PP
 192 The arguments to the
 193 .BR -d ,
 194 .BR -s ,
 195 .BR -v ,
 196 and
 197 .B -av
 198 arguments have the form
 199 .B s
 200 or
 201 .B s±r
 202 where s and r are double-precision floating point numbers.
 203 .B S
 204 is the base value and
 205 .B r
 206 if given determines a range in which the value will vary randomly
 207 from the base.
 208 .SH EXAMPLES
 209 Two rotating circles destroy each other:
 210 .IP
 211 .EX
 212 games/mkgalaxy -av 100 -d 60±50 -v 10 2000 |
 213 games/mkgalaxy -i -av -70 -d 80±50 -v 10 -o 6000,2000 -gv -80,40 3000 |
 214 games/galaxy -i
 215 .EE
 216 .PP
 217 Cool patterns made by a square galaxy:
 218 .IP
 219 .EX
 220 games/mkgalaxy -sq -av 20 5000 | games/galaxy -i
 221 .EE
 222 .SH SOURCE
 223 .B /sys/src/games/galaxy
 224 .SH SEE ALSO
 225 J. Barnes & P. Hut (December 1986). "A hierarchical O(N log N) force-calculation algorithm".
 226 .IR Nature .
 227 324 (4): 446–449.
 228 .PP
 229 .IR galaxy (6)
 230 .SH HISTORY
 231 .I Galaxy
 232 and
 233 .I mkgalaxy
 234 first appeared in 9front (Feb, 2017).