Output Files

The Lock File: lock.dat

This file is created at the beginning of a GENGA simulation. The behaviour depends on the IgnoreLockFile in the define.h file.

  • If it is set to 0, then GENGA can not be started again from time step 0.
    The lock file prevents that output files are overwritten and lost.
    GENGA can only be started again when the lock.dat file is deleted.
  • If it is set to 1, then GENGA can always be started again from time step 0, and all output files are overwritten.

Restarting GENGA from a time step > 0 is not affected by the lock file.

The Master File: master.out

The master file contains information about the used hardware and simulation progress. If an error occurs then the master file contains more details about that. The master file is not deleted at a new GENGA start.

The information file: info<name>.dat

This file contains general information about the used parameters and hardware.

At the beginning, the file lists all used parameters, the version number and driver information.

After the parameters, the file lists the timings of the kernel tuning routine (see Use self tuning kernel parameters).

At each energy output interval the file gives information of the number of close encounter.

  • Precheck-pairs: number of close encounter candidates found from the prechecker (see Finding close encounter candidates).

  • CE: total number of detected close encounter pairs (see Finding close encounter candidates).

  • groups: number of separate close encounter groups; followed by the number of close encounter groups of size 2,4,8,16,32,64,128,256,512,1024,2048 …

If an error occurs during the simulation, then in this File is written the last coordinates-Output and an information about the error.

The tuningParameters.dat file

See Use self tuning kernel parameters.

If the kernel self tuning is enabled, then this file is created, containing the values of the kernel parameters. If the kernel self tuning is disabled, then kernel parameters can be read from this file. The later option can be useful for performance measurement.

The Coordinate Output Files: Out<name>.dat

This file contains the heliocentric positions and velocities, the spin and some information about the orbit and close encounters. At the coordinate output interval, set in the param.dat file, a new output is written.

The output file format can be set to text-format or to binary-format with the Use output binary files in the param.dat file.

The number of digits in the output file names can be changed with the def_NFileNameDigits parameter in the define.h file.

Output File Format

The values of the output files depend on the Output file Format, set in the param.dat file.
Possible options are: (default = t i m r x y z vx vy vz Sx Sy Sz amin amax emin emax aec aecT encc test)

  • t: time, in years.

  • i: index of the body.

  • m: mass in Solar masses.

  • r: physical radius in AU.

  • x: x-position in AU (heliocentric).

  • y: y-position in AU (heliocentric).

  • z: z-position in AU (heliocentric).

  • vx: x-velocity in AU/day * 0.0172020989 (heliocentric) (See Units).

  • vy: y-velocity in AU/day * 0.0172020989 (heliocentric) (See Units).

  • vz: z-velocity in AU/day * 0.0172020989 (heliocentric) (See Units).

  • Sx: x-spin in Solar masses AU^2 / day * 0.0172020989. (See Units).

  • Sy: y-spin in Solar masses AU^2 / day * 0.0172020989. (See Units).

  • Sz: z-spin in Solar masses AU^2 / day * 0.0172020989. (See Units).

  • amin: minimal value of semi major axis range for aecount (See aeLimits).
    Optional.
  • amax: maximal value of semi major axis range for aecount (See aeLimits).
    Optional.
  • emin: minimal value of eccentricity range for aecount (See aeLimits).
    Optional.
  • emax: maximal value of eccentricity range for aecount (See aeLimits).
    Optional.
  • k2: potential Love number of degree 2, dimensionless.
    (needed when given as initial conditions)
  • k2f: fluid Love number of degree 2, dimensionless.
    (needed when given as initial conditions)
  • tau: time lag in day / 0.0172020989 (See Units).
    (needed when given as initial conditions)
  • Ic: moment of inertia, dimensionless (See Units).
    (needed when given as initial conditions)
  • aec: aecount is the number of time steps since the last coordinate output time in which the particles semi major axis and eccentricity where in the aecount box limits (see aeLimits).
    Optional.
  • aecT, aecountT is the integrated value of all previous aecount values.
    Optional.
  • encc: enccountT is the number of time steps since the simulation start in which the particle was in a close encounter with another (massive) particle.
    Optional.
  • Rc: Critical radius for close encounters, rcrit, in AU
    Optional.
  • test: value stored in the test arrays.
    Optional.

When the Use output binary files option is used, then the files contain the same data as described before with the following types:

  • t: double, 64bit

  • i: int, 32bit

  • m: double, 64bit

  • r: double, 64bit

  • x: double, 64bit

  • y: double, 64bit

  • z: double, 64bit

  • vx: double, 64bit

  • vy: double, 64bit

  • vz: double, 64bit

  • Sx: double, 64bit

  • Sy: double, 64bit

  • Sz: double, 64bit

  • amin: float, 32bit

  • amax: float, 32bit

  • emin: float, 32bit

  • emax: float, 32bit

  • k2: double, 64bit

  • k2f: double, 64bit

  • tau: double, 64bit

  • Ic: double, 64bit

  • aec: float, 32bit

  • aecT: float, 32bit

  • encc: unsigned long long, 64bit

  • Rc: double, 64bit

  • test: double, 64bit

The structure of the coordinate output files depends on the parameters FormatS, FormatT, FormatP and FormatO. Here we describe the possible choices:

The tools Convert_P1T0_to_P0T1 and Convert_P0T1_to_P1T0 can be used to convert output files between different formats.

FormatS = 0, FormatT = 0, FormatP = 1, FormatO = 0: Out<name>_<time step>.dat

In this format, at each coordinate output interval, a new file is created which contains all particles. In the multi simulation mode, each sub simulation folder contain individual files:

t i1 m1 r1 x1 y1 z1 vx1 vy1 vz1 Sx1 Sy2 Sz1 ...
t i2 m2 r2 x2 y2 z2 vx2 vy2 vz2 Sx2 Sy2 Sz2 ...
.
.
.
t in mn rn xn yn zn vxn vyn vzn Sxn Syn Szn ...

FormatS = 1, FormatT = 0 FormatP = 1, FormatO = 0: Out<name>.dat

Here the difference is that in the multi simulation mode, the coordinates are not written in the sub simulation folders, but in the main folder. The output files contain all particles from all sub simulations.

FormatS = 0, FormatT = 1 FormatP = 1, FormatO = 0: Out<name>.dat

Here all the time steps are written to the same file, containing all time steps and all particles.

FormatS = 1, FormatT = 1 FormatP = 1, FormatO = 0: Out<name>.dat

Here all time steps are written to the same file, containing all time steps and all particles from all sub simulations.

FormatP = 0: Outp< index>.dat

Here all particles are written to different files, containing all time steps.

FormatS = 0, FormatT = 0, FormatP = 1, FormatO = 1: Out<name>_<output step>.dat

Here the difference is that the output files are not named after the time step, but the output step. When the simulation is interrupted at a time step in between of two output steps, then a backup file ‘Outbackup<name>_<time step>.dat’ is created. This backup step can be read by the restart option -R -1. To restart from a normal output file, the real time step, and not the output step must be chosen.

FormatT = 0, and FormatP = 0

This option is not possible, it is equivalent to FormatT = 1 and FormatP = 0

FormatS = 1, FormatT = 1, and FormatP = 0

This option is not possible, it is equivalent to FormatS = 0, FormatT = 1 and FormatP = 0

Number of outputs per interval

When this number is larger than 1, then at each coordinate output interval, n consecutive outputs are written.

For example, when the following numbers are set

  • Coordinates output interval = 100

  • Number of outputs per interval = 5,

then the following time steps are written as outputs: 0, 96, 97, 98, 99, 100, 196, 197, 198, 199, 200, …

The Irregular Coordinate Output Files: OutIrr<name><time>.dat

These files are only created when the output calendar file is used. The file contains the same structure as the The Coordinate Output Files: Out<name>.dat but at the time specified in the calendar file. The number in the file name corresponds to the line in the calendar file. See Irregular output times.

The number of digits in the output file names can be changed with the def_NFileNameDigits parameter in the define.h file.

Keplerian-Elemets Output Files: aei<name>.dat

The Coordinate output files can be uses to generate Keplerian-Elements output files with the KE tool. These files contain the following:

time i a e inc Omega w Theta E M m r

with

  • time: time, in years

  • i: index

  • a: semi major axis, in AU

  • e: eccentricity:

  • inc: inclination, in radians

  • Omega: longitude of the ascending node, in radians

  • w: argument of periapsis, in radians

  • Theta: true anomaly, in radians

  • E: eccentric anomaly, in radians

  • M: mean anomaly, in radians

  • m: mass, in Solar masses

  • r: radius, in AU

Barycentric output Files: OutBary<name>.dat

The barycentric coordinate output files can be generated with the ConvertHelioToBarry tool.

The files contain the same information as the original heliocentric coordinate output files, but they contain at the beginning an additional particles, representing the barycentrum, with an index of -1.

The Energy Output File: Energy<name>.dat

This file contains information about the number of particles, angular momentum and the energy. At the Energy output interval, set in the param.dat file, a new line in this file is written. The format is the following:

time0  N  V  T  LI  U  ETotal  LTotal  LRelativ  ERelativ
time1  N  V  T  LI  U  ETotal  LTotal  LRelativ  ERelativ
.
.
.

with

  • time in years

  • N: Number of particles

  • V: Total potential energy , in \(M_\odot AU^2 / day^2\)

  • T: Total Kinetic energy, in \(M_\odot AU^2 / day^2\)

  • LI: Angular momentum lost at ejections, in \(M_\odot AU^2 / day\)

  • U: Inner energy created from collisions, ejections or gas disk, \(M_\odot AU^2 / day^2\)

  • ETotal: Total Energy, in \(M_\odot AU^2 / day^2\)

  • LTotal: Total Angular Momentum, in \(M_\odot AU^2 / day\)

  • LRelativ: (LTotal_t - LTotal_0)/LTotal_0, dimensionless

  • ERelativ: (ETotal_t - ETotal_0)/ETotal_0, dimensionless

The tool cleanEnergy.py in the tools directory can be used to clean the Energy files from restarting data.

See Cleaning the Energy files.

The Irregular Energy Output File: EnergyIrr<name>.dat

See Irregular output times.

This file is only created when the output calendar file is used. The file contains the same structure as the regular The Energy Output File: Energy<name>.dat, but at output times, specified in the output calendar file.

The Execution Time File: time<name>.dat

This file contains the execution time spent for the corresponding Coordinate Output interval, in seconds. The last line contains the total execution time in seconds. The first column indicates the time step. This last entry in the file is used for the automated restart (restart timestep = -1).

When the code was interrupted in between of two output intervals, then the time file contains additional lines with the divided times in it. If the code was interrupted many times due to e.g. limited wall times, the time files can get hard to read.

The tool cleanTime.py in the tools directory can be used to clean the time files and add the divided times together to the original coordinate output intervals.

See Cleaning the time files.

The Collisions File: Collisions<name>.dat

See Collisions.

In this file are listed the details of the collisions between particle i and j. The precision of the collision output can be adjusted with the Collision Precision argument in the param.dat file (See Collision precision). The file contains the following columns:

time indexi mi ri xi yi zi vxi vyi vzi Sxi Syi Szi indexj mj rj xj yj zj vxj vyj vzj Sxj Syj Szj
.
.
.

The Tshift Collisions File: CollisionsTshift<name>.dat

See Backtrace Collisions (TShift).

In this file are listed the details of the backtraced collisions between particle i and j. The collision time shift option can be set by the Collision Time Shift argument in the param.dat file. This file is only created when Collision Time Shift is used. The file contains the following columns:

time indexi mi ri xi yi zi vxi vyi vzi Sxi Syi Szi indexj mj rj xj yj zj vxj vyj vzj Sxj Syj Szj
.
.
.

The Stop-at-collision-file: OutCollision.dat

See Stop at Collision.

This file is only created when the Stop at Collision option is enabled. It contains all particles of the simulation at the time when the first collision occurred. The file contains the same columns as the normal output files.

The encounter-file: Encounters<name>.dat

See Report Encounters.

This file is only created when the Report Encounters option is enabled. It contains the details of each encounter event:

time indexi mi ri xi yi zi vxi vyi vzi Sxi Syi Szi indexj mj rj xj yj zj vxj vyj vzj Sxj Syj Sz
.
.
.

The ejection file: Ejections<name>.dat

See Ejections.

This file contains the details of all ejection events, in the format:

time index m r x y z vx vy vz Sx Sy Sz case
.
.
.

with: case = -3 for bodies removed at the outer boundary, and case = -2 for bodies removed at the inner boundary.

The stellar evolution file: Star<name>.dat

See Tidal Forces.

This file is only produced when Use Tides or Use Rotational Deformation are enabled. The file contains the parameters of the star in the format:

time mass radius Spin_x Spin_y Spin_z Ic Love-number fluid-Love-number time-lag
.
.
.

The Irregular stellar evolution file: StarIrr<name>.dat

See Tidal Forces.

This file is only created when the output calendar file is used. The file contains the same structure as the regular The stellar evolution file: Star<name>.dat, but at output times, specified in the output calendar file.

The Fragments File: Fragments<name>.dat

See Model for small bodies collisions.

This file is only created when the model for small bodies collisions UseSmallCollisions or the particle creation mode Create Particles in the param.dat file are enabled. The file contains information about fragmentation and rotation reset events:

time index m r x y z vx vy vz Sx Sy Sz event
.
.
.
the ‘event’ indicates the following:
  • 0: | rotation rate reset
    Used in UseSmallCollisions = 1 or 2 mode.
  • -1: | Collision, the particle is destroyed, and it is replaced with new fragments (listed in the next lines with event=1 or event=2 of this file)
    Used in UseSmallCollisions = 1 or 3 mode.
  • 1: | A new fragment particle. The original body is the last body in this file with event = -1.
    Used in UseSmallCollisions = 1 or 3 mode.
  • 2: | A new fragment particle. The original body is the last body in this file with event = -1.
    This body is too small and it is directly removed from the simulation.
    Used in UseSmallCollisions = 1 or 3 mode.
  • 10: | A new particle is created.
    Used in Create Particles = 1 mode.

Each newly created fragment gets a new, increasing, index number. This file permits to reconstruct the collision and fragmentation history of every particle.

The a-e and a-i grid files: aeCount<grid name><time step>.dat

See The a-e and a-i grid.

These files are only written when the aegrid option is used. The files contain four matrices, separated by a blank line.

  • a-e counts since the last coordinate output, size Na x Ne

  • a-e counts since the beginning of the simulation, size Na x Ne

  • a-i counts since the last coordinate output, size Na x Ni

  • a-i counts since the beginning of the simulation, size Na x Ni

The Poincare surface of section file: Poincare<name><timeInterval>.dat

See Poincare surface of section

The file contains the coordinates of the Poincare surface of section:

time index x vx
.
.
.

The crossing events are written consecutively to the file. After each coordinate output interval, another file is created to reduce the file sizes.