Gravity Graphics Command Line Options

Return to the project page
Return to the index

I know there isn't any good documentation on the command-line options and switches for the Linux grfxgrav project, and I'm sorry. I hope with this document to fill that void. All defaults presented are for grfxgrav-1.2; however as I am writing this I have finalized version 1.2 and if I forget to change the defaults displayed on this page to those of the release, forgive me.

This page contains a couple segments of the source code for this program. All source code on this page is part of the project and should be treated accordingly in terms of copyright and licensing. That said, it is open source, and I don't care, unless you would violate the terms of the license; and anyway, it's hardly anything worth copying, just small segments meant to convey a piece of the algorithm.

List of options by type:
*{+(default:on), -(default:off)} Boolean options
+alwayscircle
+distkills
+drawsun
-oldequation
-randomize
+stuffdies
+sunflares
+sunkills
-sunzoom
+unigrav
+walls
-zoomspacing

*Integer options [shortform]: Default
arraysize [as] : 360
colodds [c] : 200
delay [d] : 20
minheight [h] : 2
metadelta [md] : 18
sunsize [sr] : 6
sunx [sx] : 0
suny [sy] : 0
zoom [z] : 6

*Floating point options [shortform]: Default
flarevelocity [fv] : .95
flareheight [fh] : 1.1
gravity [g] : .00000667
simspeed [ss] : .00125
spacing [s] : 1.
velocity [v] : .625
wallbrakes [w] : .5

Note on parameter exclusions:
Turning off drawsun disables flareheight, flarevelocity, sunflares, sunkills, sunsize, sunx, suny, and sunzoom.
Turning on randomize disables alwayscircle, metadelta, minheight, spacing, and zoomspacing.
Turning off stuffdies disables distkills, sunkills, and sunflares.
Turning off sunflares disables flarevelocity and flareheight.
Turning off walls disables wallbrakes.

Explanation of Options by Alphabetical Order:

alwayscircle (b): With this option off, and when randomize is not set, each planet is spaced 1 degree (pi/180 radians) from the last one, according to the following algorithm:
(ht=minheight md=metadelta sc=spacing i=index in the array)
pList[i].o.x=(ht+(i%md)*sc)*cos(i*M_PI/180);
pList[i].o.y=(ht+(i%md)*sc)*sin(i*M_PI/180); Therefore, any number not a multiple of 360 will result in partial circles which may not be as aesthetically pleasing, depending on your tastes. What alwayscircle does is adjust the separation of the planets according to the size of the array, so that precisely one revolution is made.

arraysize (i): Exactly as the name states, this is how many planets are put into the array when the simulation launches. Please note that there is no serious checking done to ensure that memory is properly allocated, so if you run your machine out of memory with too many planets, it's your fault, not mine; I don't have the time or inclination to make this program 100% compatable and foolproof at the moment.

colodds (i): This is used to determine how often a planet changes color:
switch(rand()%colOdds){
case 0:pList[i].col--;if(pList[i].col<0)P.col+=5;break;
case 1:pList[i].col++;if(pList[i].col>4)P.col-=5;break;
default:break; } Set to 0 to disable. As one can assume from the code segment, there are 5 colors; in order from 0, white, red, blue, green, yellow. That's essentially arbitary; I have never been able to recreate the faux-twinkling that I loved so much from the very earliest versions of the program, but this scheme works alright.

delay (i): The value of delay is used to set a QTimer. Whenever it times out, the display is updated. The QTimer will be stopped when the window is doubleclicked or (hopefully, supposedly) when it is minimized, windowshaded, or otherwise disabled, although I am not certain those work and in fact think they don't. It will be restarted when doubleclicked again, or when the window is restored from being minimized, etc.

distkills (b): If stuffdies, and this option is set, planets too long outside of the viewing window will 'die', and cease to be calculated ever again. This shouldn't be necessary if walls are set; however, if the initial conditions are such that some planets start outside the viewing window, they will probably never be used, if this is set, which can lead to interesting patterns. See the Author's Notes page.

drawsun (b): This determines if the sun, the white ball in the center is drawn during each update. Currently you can have the sun in any color as long as it's white. See also sunkills, sunsize, and sunzoom.

flareheight (f): See sunflares. This is multiplied by the size of the sun to determine how far from the center of the sun 'solar flares' originate.

flarevelocity (f): See sunflares. This is multiplied by the escape velocity of a particle at the sun's surface to determine the speed (not velocity, really) it is given at origination.

gravity (f): This is the gravitational constant G; except more precisely, it's that constant multiplied by the mass of the sun. That is to say, in the physics equation a[gravity]=G*M/(d*d), (derived from the equation F[gravity]=G*M*m/(d*d) ) this value is G*M. A point of interest is that there is no check to determine whether gravity is negative or zero; negative values lead to "antigravity" where the sun repels the planets, while zero gravity means... well, it means the planets travel in a straight line (unless they hit a wall!). See the Author's Notes page.

metadelta (i): This is a word I made up, because I've been using the variable name 'md' for this place in my programs virtually since their conception. Whether this is the same word I intended when I wrote that, I haven't the foggiest clue. This option is only useful if randomize is not set. See the code segment and description for minheight. The only real way I can think to explain it is with the code, which is attached to minheight and arraysize; the distance of any planet's initial condition from the center of the sun is minheight plus the index of the planet in the array modulo the metadelta number, all multiplied by the spacing constant; that is, for h=5,md=3,s=1, the height of the first seven planets would be 5,6,7,8,5,6,7: 5+(0%3)*1,5+(1%3)*1, etc.

minheight (i): This option is only useful if randomize is not set. See the code segment (the centered text) in the section on arraysize, and also metadelta, above. As it was designed, minheight sets the minimum distance during planet initialization, as defined by the algorithm below:
(ht=minheight md=metadelta sc=spacing i=index in the array)
...x=(ht+(i%md)*sc)*cos(...)
...y=(ht+(i%md)*sc)*sin(...) However with the addition of the variable spacing constant 'spacing', it is possible to throw negative numbers into the mix, whereby minheight is actually the highest of the initial conditions. Go figure. See the Author's Notes page.

oldequation (b): This is the grfxgrav-killer. I wrote the first versions of this project as a sophomore or so in high school, before I'd gotten into physics in any detail, and so my equations were wrong; pleasing to look at, but wrong. But since I didn't think about them, since they'd been there the whole time, I didn't notice. Specifically, the Old Equations are v+=a*t; x+=v*t where origionally t=1 (t really being delta t, hence the '+=' ) and wasn't coded; later t was added to x(t) but not v(t), then to both, then just recently I took at look at what I was doing and, d'oh! As anyone who's taken physics SHOULD know, v+=a*t; x+= v*t+(1/2)*a*t*t. Unfortunately, as things are with the program at the moment, this correct formula makes orbits decay immediately, so that the simulation loses the beautiful coordination and synchronicity it had from the beginning; this may be simply because I haven't stumbled upon the correct formula for determining good initial velocities; it doesn't much matter at the moment, I'm quite unhappy about it all. Set oldequation to get the old, wrong, neat-looking simulation back, or unset it to fiddle with a more realistic simulation.

randomize (b): This discards the neat, patterned setup for initial conditions wherein planets are spaced around the center or sun, and instead pretty much sticks 'em anywhere. There are some minor problems that I haven't worked out quite yet, but I don't care that much since I don't use it often. Windows 'grfxgrav3.exe' is essentially 'grfxgrav.exe' with randomized planets; this puts that functionality into the project as a command switch.

simspeed (f): This is the reason I discovered the problem with my old equation; origionally called 'accuracy' in the windows versions because the higher you set it, the faster things fell, and I said aha! it must be more correct that way. But as I sat and looked at it recently, I thought to myself, that's just not right, and eventually it hit me. In this revised version, it's exactly what it says; and please note its meaning is reversed from previous versions! Currently simspeed is the delta-t in all the equations v=v+a*dt, x=x+v*dt+(1/2)*a*dt*dt; and for the old equations x=x+v*dt. In previous versions of grfxgrav, dt=(1./ss) where ss=simspeed=an integer.

spacing (f): This option is only meaningful when randomize is not set. The displacement from minheight as determined by metadelta is multiplied by this number; see the code segment in the minheight description. If zoomspacing is set, this value is divided by the zoom.

stuffdies (b): This switch determines whether objects that meet certain criteria (see distkills, sunkills) are removed from the simulation. This is pivotal to the mechanism behind sunflares, because when that is set, any 'dead' slots in the array are randomly filled with 'solar flares' taken from the sun's mass.

sunflares (b): This switch is only meaningful if drawsun is set and stuffdies, and if planets are killed with either distkills or sunkills. With this set, any planets that die have their slot in the data array filled by a 'solar flare'; specifically an ejection of solar mass at a random point on the sun's 2d surface with a velocity magnitude equal to its escape velocity multiplied by flarevelocity and a velocity angle somewhat randomized from perpendicular to the sun's surface. It is worthwhile to note that it is given a random mass, the magnitude of which is removed from the sun's mass, just as planets that die when they hit the sun add their mass to it.

sunkills (b): This switch is only meaningful if drawsun is set and stuffdies. If any planet falls into the sun, it is removed from the simulation. This frees a space for sunflares if that option is set. The mass of the planet is added to the sun's mass, which is currently only meaningful in unigrav mode.

sunsize (i): This is the integer radius of the sun if drawsun is set; if sunzoom is set, this value is multiplied by zoom.

sunx and suny (i): This allows the initial position of the sun to be set arbitrarily; note that this affects the gravitation of all planets in the simulation, but not their initial placement; also note that in unigrav mode, the sun is free to move by the whims of gravity, while in single-grav mode (nounigrav), the sun is fixed in place for the duration of the simulation.

sunzoom (b): If set, sunsize is multiplied by zoom; that is, while this option is set, the size of the sun is dependant upon the zoom; when it is not set, the size at which it is drawn is the same regardless of the zoom level.

unigrav (b): Sets Universal Gravitation mode. In unigrav mode, each planet has its own mass and therefore gravitational attraction upon each other planet; in single gravitation, only the sun pulls on the planets. See Author's Notes page.

velocity (f): Sets the initial speed of every planet in the system. Please note that having a poorly chosen velocity can make the simulation very boring indeed. Initial velocities are perpendicular to the vector connecting a planet and the center of the simulation.

walls (b): If set, planets bounce instead of leaving the window. This is perfectly capable of causing a nice, orderly simulation to be lost in a chaotic stream of flying particles, especially if sunkills is not set.

wallbrakes (f): This option is only meaningful if walls is set. This constant is multiplied with the value of a planet's velocity when it bounces off of a wall. This can, for instance, slow down particles that pass to close to the center of gravitation (if nosunkills, etc) and are hyper-accelerated. Or, set this greater than one to cause the entropy in the system to perpetually increase; use antigravity (negative values for gravity) and watch the fun! See Author's Notes page.

zoom (i): This sets the degree to which the view of the simulation is zoomed in; that is, for zoom 2, a planet at (4,5) would be at (8,10); etc. See also zoomspacing, sunzoom.

zoomspacing (b): If set, spacing is divided by the zoom; that is, if this is set, the spacing of the planets (not the height; that's independant of this setting) is independant of the zoom, so at higher magnifications, the planets are actually a lot closer together, in terms of the actual values (the ones used in calculation). See also spacing.