Using the Grav-Sim Simulators

There are 3 Grav-Sim command-line simulators (note that Windows executables have the extension .exe):

  • FastSim
  • GravSim
  • FineSim

They all accept the same set of arguments.

You can specify a model file to load (default "model.csv") with the –f option, e.g.:

> FastSim –f model1000.csv

You can specify a model file to save (default "result.csv") with the –r option, e.g.:

> GravSim –f model100.csv –r result100.csv

You can choose to save an orbit file (default "none") with the –o option, e.g.:

> GravSim –f model10.csv –o orbit10.csv

You can run a simulation for a specific simulated-time with the –m option, e.g.:

> FineSim –f model2.csv –m 28.203

For help on the other options available, try:

> FineSim –-help

FineSim performs gravitational simulations with n-body models at an accuracy of up to 30 decimal digits.

It is part of the Grav-Sim software download. For more details see http://www.grav-sim.com.

Copyright (c) Mark Ridler 2009

Usage: FineSim [OPTIONS]...
-h, --help Print help and exit
--detailed-help Print help, including all details and hidden
options, and exit
-V, --version Print version and exit
Main Options:
-f, --file=filename Model input filename (or stdin)
(default=`model.csv')
-r, --result=filename Model output filename (or stdout)
(default=`result.csv')
-o, --orbit=filename Orbit output filename (or none)
(default=`none')
-m, --sim-time=FLOAT The time after which the simulation ends
(default=`1.0')
-n, --log-points=INT The number of log points per sim-time
(default=`16')
-l, --level=INT Determines the level of simulation
(default=`1')
-i, --integrator=STRING Choice of integration method (possible
values="forwardeuler", "forwardplus",
"protohermite", "leapfrog",
"multistep", "rungekutta2n",
                                "rungekutta2n_fsal", "rungekutta3",
"rungekutta4", "rungekutta4n",
"chinchen", "chinchenoptimised",
"hermite", "hermite6", "hermite8"
default=`hermite8')
-a, --accelerator=STRING Choice of acceleration method (possible
values="bruteforce", "ridlertree"
default=`bruteforce')
-t, --timestep=STRING Choice of time-step type (possible
values="constant", "shared",
"individual" default=`individual')
-s, --softening=FLOAT Determines the gravity softening parameter
(default=`0.0')
Fine-Tuning Options:
--block-timesteps=STRING Whether to use block timesteps (possible
values="yes", "no" default=`yes')
--batch-size=INT Number of bodies processed in each batch.
 (default=`1024')
--branch-factor=INT Number of children per node for a ridlertree.
(default=`4')
--theta-min-multipole=FLOAT
Minimum separation for the multipole terms.
(default=`1.25')
--theta-max-quadrupole=FLOAT
Maximum separation for the quadrupole term.
(default=`100.0')
 

File Formats

Grav-Sim uses comma-separated-values (.csv) files for convenience. The layout is simple, efficient and human-readable.

The files can be loaded into any text editor and are readily accepted by a variety of other software packages such as Microsoft Excel.

Model File Format

Each body appears once in a Grav-Sim model file on a separate line. Each body has a unique id, a mass, a position and a velocity. Position and velocity are 3D vectors, specified as x,y,z components.

The first line in the file contains the header info:

<no. of bodies>,Mass,Pos(x),Pos(y),Pos(z),Vel(x),Vel(y),Vel(z)

All subsequent lines contain 8 columns of numbers separated by commas.

Model Files in a Text Editor

For example, the Grav-Sim 2-body model file "model2.csv" appears as follows in a text editor:

2,Mass,Pos(x),Pos(y),Pos(z),Vel(x),Vel(y),Vel(z)
0,1.0,0.0,0.0,0.0,0.0,0.02,0.0 
1,0.1,5.0,0.0,0.0,0.0,-0.2,0.0

Model Files in Microsoft Excel

If you view it in Microsoft Excel, it appears as follows:

2MassPos(x)Pos(y)Pos(z)Vel(x)Vel(y)Vel(z)
01.00.00.00.00.00.020.0
10.15.00.00.00.0-0.20.0


Orbit File Format

Each body can appear on multiple lines in a Grav-Sim orbit file. Each line represents a portion of an orbit and has a unique id, a mass, a starting position and a finishing position. The unique ids are carried across from the model file and let you tally which body is which. Positions are 3D vectors with x,y,z components as before.

The first line in the file contains the header info:

<no. of bodies>,Mass,Pos1(x),Pos1(y),Pos1(z),Pos2(x),Pos2(y),Pos2(z)

All subsequent lines contain 8 columns of numbers separated by commas.

Orbit Files in a Text Editor

For example, if you run a Grav-Sim simulation on the 2-body model file "model2.csv" and output the orbits to a file "orbit2.csv", the first few lines would appear as follows in a text editor:

2,Mass,Pos1(x),Pos1(y),Pos1(z),Pos2(x),Pos2(y),Pos2(z)
1,0.1,5,0,0,4.99,-0.141318,0
0,1,0,0,0,0.00100035,0.0141318,0
1,0.1,4.99,-0.141318,0,4.95992,-0.282009,0
0,1,0.00100035,0.0141318,0,0.00400733,0.0282009,0

...

Orbit Files in Microsoft Excel

If you load "orbit2.csv" into Microsoft Excel, it would appear as follows:

2MassPos1(x)Pos1(y)Pos1(z)Pos2(x)Pos2(y)Pos2(z)
10.15004.99-0.1413180
010000.001000350.01413180
10.14.99-0.14131804.95992-0.2820090
010.001000350.014131800.004007330.02820090
...

Using the Grav-View Viewer

A minimal viewer is provided for the purpose of visualising Grav-Sim model and orbit files:

  • GravView

This also uses the -f option to specify the file to load.

> GravView –f model1000.csv

Depending on whether the file loaded is a model file or an orbit file, GravView either runs the simulation in real-time as you watch or replays the sequence as pre-recorded in the file.

The images in the Models section were produced using GravView.