# How to use it¶

## Command line options¶

The Available options for using GraviDy from the command line are the following:

• -h Print the help message, including all the available options.
• Mandatory
• -i Option to specify the initial conditions to be used.
• -t Integration time in N-body units, if this is not specified, the default value is $$1$$.
• Optional
• -o Specify the name of the output files that will be used to generate all the simulations logs.
• -s The default value of the softening $$\epsilon$$ is $$1e-4$$ but can be changed using this option.
• -e The default value of $$\eta$$ is $$0.01$$, but can be changed using this option.
• -p Instead of writing a file(s) with all the simulation logs, this can be printed on the screen (stdout).
• -z Time interval to get the output from the code, the default is 0.125 which is the maximum timestep available.
• Extra
• -l Optionally, the lagrange radii can be calculated and printed using this option.
• -a With this option is possible to print all the information of every particle, including Mass, Position, Velocity, Forces and Time-step.
• -g With this option is possible to set the amount of GPUs that will be used.

As we mentioned before, all the allowed option can be displayed on the standard output using the -h option.

$./gravidy -h GraviDy: -h [ --help ] Display this message Required options: -i [ --input ] <filename> Input data filename -t [ --time ] <value> (=1) Integration time (In N-body units) -r [ --resume ] <filename>.info Resume a simulation with an .info file Elective options: -o [ --output ] <filename> Output data filename -s [ --softening ] <value> Softening parameter (default 1e-4) -e [ --eta ] <value> ETA of time-step calculation (default 0.01) -p [ --screen ] Print summary in the screen instead of a file -z [ --interval ] <value> Output time interval (default 0.125) Extra options: -l [ --lagrange ] Print information of the Lagrange Radii in every integration time -a [ --all ] Print all the information of N-particles in every integration time -g [ --gpu ] <value> (=0) GPUs to use, by default is the maximum available devices (use even numbers)  ## Initial conditions¶ GraviDy reads an ASCII file with the information of all the particles, in the order: ID, Mass, Position and Velocity. The following is an example of the format: id_1 m_1 rx_1 ry_1 rz_1 vx_1 vy_1 vz_1 id_1 m_2 rx_2 ry_2 rz_2 vx_2 vy_2 vz_2 id_1 m_3 rx_3 ry_3 rz_3 vx_3 vy_3 vz_3 ... id_1 m_N rx_N ry_N rz_N vx_N vy_N vz_N  ## Output files¶ Running a simulation without using the -p option, will generate the following files: $ ./gravidy-gpu -i ../input/04-nbody-p1024_m1.in -o MyOut -t 1
[2017-02-01 21:39:41] [INFO] GPUs: 1
[2017-02-01 21:39:41] [INFO] Splitting 1024 particles in 1 GPUs
[2017-02-01 21:39:41] [INFO] GPU 0 particles: 1024
[2017-02-01 21:39:43] [SUCCESS] Finishing...

$ls MyOut.out.info MyOut.out.log MyOut.out.snapshot_0000 MyOut.out.snapshot_0001 MyOut.out.snapshot_0002 MyOut.out.snapshot_0003 MyOut.out.snapshot_0004 MyOut.out.snapshot_0005 MyOut.out.snapshot_0006 MyOut.out.snapshot_0007 MyOut.out.snapshot_0008 MyOut.out.snapshot_0009  ### The info file¶ This file will contain a brief overview of the general aspects of the simulation at the moment it started: $ cat MyOut.out.info
# NumberParticles:                             1024
# Softening:                                 0.0001
# EtaTimestep:                                 0.01
# IntegrationTime:                                1
# PrintScreen:                                    0
# InputFilename:      ../input/04-nbody-p1024_m1.in
# OutputFilename:                         MyOut.out
# SnapshotNumber:                                 9

• NumberParticles: The number of the particles in the initial condition file.

• Softening: $$\epsilon$$ parameter for the softened force interaction.

$\begin{split}\boldsymbol{\ddot{r}}_{i} = -G \sum\limits^{N}_{\substack{j=1\\j\neq i}} {m_{j} \over (r^{2}_{ij} + \epsilon^{2})^{3/2} } \boldsymbol{r}_{ij},\end{split}$
• EtaTimestep: $$\eta$$ parameter for the time step calculation.

$\Delta t_{i} = \sqrt{\eta\frac{|\boldsymbol{a}_{i}||\boldsymbol{a}_{i}^{(2)}|+|\boldsymbol{j}_{i}|^{2}}{|\boldsymbol{j}_{i}||\boldsymbol{a}_{i}^{(3)}|+|\boldsymbol{a}_{i}^{(2)}|^{2}}}$
• IntegrationTime: Integration time specified by the option -t.

• PrintScreen: If the option -p was enabled or not.

• InputFilename: Initial conditions relative path.

• OutputFilename: Base name of the output files, specified by the option -o.

• SnapshotNumber: Number of snapshots generated until the integration stopped.

### The log file¶

The information on this file will be displayed on the screen if the option -p is specified, otherwise:

$cat MyOut.out.log # IteTime Iter Nsteps Energy RelE CumE ElapsedTime GFLOPS 00 0.000 0 0 -2.5687759360e-01 0.000000e+00 0.000000e+00 1.081110e-01 0.000 00 0.125 698 30093 -2.5687765551e-01 2.410004e-07 2.410004e-07 4.642270e-01 6.505 00 0.250 1262 61319 -2.5687762708e-01 1.106466e-07 1.303538e-07 7.479802e-01 7.135 00 0.375 1897 91571 -2.5687761632e-01 4.192094e-08 8.843281e-08 1.033500e+00 7.340 00 0.500 2530 121963 -2.5687759445e-01 8.512492e-08 3.307881e-09 1.325059e+00 7.517 00 0.625 3132 150924 -2.5687760190e-01 2.899267e-08 3.230055e-08 1.588835e+00 7.640 00 0.750 3725 180446 -2.5687759832e-01 1.394194e-08 1.835861e-08 1.849849e+00 7.733 00 0.875 4354 212425 -2.5687773276e-01 5.233652e-07 5.417238e-07 2.147411e+00 7.803 00 1.000 5160 244165 -2.5687767307e-01 2.323583e-07 3.093654e-07 2.489176e+00 7.730  The columns of this file correspond to: • IteTime: Current integration time, by default multiple of the maximum timestep allowed. • Iter: Amount of iterations, integration steps. • Nsteps: Amount of particles that have been updated up to a certain integration time. • Energy: Current total energy of the system. • RelE: Relative energy error, $$\frac{E_{t} - E_{t-1}}{E_{t-1}}$$. • CumE: Cumulative energy error, $$\frac{E_{t} - E_{t,0}}{E_{t,0}}$$. • ElapsedTime: Wall clock time. • GFLOPS: Floating Point Operations Per Second approximation. ### The snapshot files¶ Every snapshot correspond to the current information of the system at a certain time. The file is generated in ASCII plain text. $ head -n 5 MyOut.out.snapshot_0002
# Time:0.2500
1   9.765625e-04   1.142414e+00  -1.065075e+00  -3.423198e-01  -1.796895e-01  -4.357895e-02   2.527831e-01
2   9.765625e-04   3.938875e-01  -9.265678e-01  -3.237272e-01   7.087970e-02   2.682987e-01  -1.318306e-01
3   9.765625e-04   1.335213e-01   3.308229e-01  -3.002197e-01  -6.835964e-01   1.240149e-01  -3.313794e-01
4   9.765625e-04   2.484300e-01   2.496406e-02  -5.006182e-02  -7.771124e-01   4.239778e-01   2.027512e-01
...


The first line display the current integration time of the snapshot. Columns in this file show ID, Mass, Rx, Ry, Rz, Vx, Vy and Vz for every particle.