obreschkow / nbodyx Goto Github PK

OVERVIEW
====================================================================================================================

nbodyx is a simple brute-force code to run direct gravitational N-body simulations. It uses a variable block timestep
and lets the user choose between a range of integrators, including 4th and 6th order integrators for high-accuracy
simulations. Basic top-hat smoothing is available as an option. The code also allows the definition of
background particles that are fixed or in uniform motion, not subject to acceleration by other particles. (See
ics_example.txt for details of how such particles are specified.)

The code can either be used as a stand-alone tool or called via the 'nbody' package from the R statistical language.

V0.0  02/08/2018: First release
V1.0  10/08/2021: Integration of shared modules, enhanced interface and documentation
V1.1  25/08/2021: Optional periodic boundary conditions
V1.2  08/09/2021: New run-time parameter to exclude background particles in output files
V1.3  10/09/2021: New run-time parameter to control the floating-point precision of output files
V1.4  12/01/2022: Fixed bug causing background particles to move incorrectly
V1.5  08/11/2022: Option to specify a parameterised external acceleration field
V1.6  12/01/2023: Added examples of Kepler and Hernquist potentials to module_acceleration

Copyright Danail Obreschkow ([email protected])


QUICK START ON A GENERIC LINUX SYSTEM
====================================================================================================================

1) Install gfortran (which is part of gcc).

2) In a terminal, download nbodyx
   > git clone https://github.com/obreschkow/nbodyx
   
3) Go to the new nbodyx directory:
   > cd nbodyx
   
4) Compile the code: (Depending on your system, the makefile might need to be modified before calling make.)
   > make
   
5) Test if the code has properly compiled:
   > ./nbodyx -version
   This should just return the version number of nbodyx.
   
6) Run a default test simulation:
   > ./nbodyx
   This should produce the new sub-directory 'output'. Check if this directory contains snapshot files, called
   snapshot_######.txt, and a summary file, called statistics.txt.

7) To run your own simulation, edit the parameter file and ics file directly, or use the 'nbody' package in R as
   an interface.
   
NOTE: By default, nbodyx uses 8-byte double-precision floating-point numbers for all calculations. If very high
      positional accuracy is needed, you can compile the code with 16-byte floating-point positions using
      > make kind=16
      Make sure to run
      > make clean
      before changing the kind. Note that some compilers may not support 16-byte floating-point numbers.


QUICK START ON ICRAR'S HYADES CLUSTER
====================================================================================================================

# install and compile nbodyx in your home directory
cd ~
rm -rf nbodyx/ # remove previous nbodyx directory
git clone https://github.com/obreschkow/nbodyx # install updated version
cd nbodyx # change to nbodyx directory
module load gfortran # load required modules
make # compile code
./nbodyx -version # check version


ARGUMENTS
====================================================================================================================

Generally, nbodyx is called as
> ./nbodyx [-option argument] [-option argument] ...

-parameterfile (default parameters.txt): path+filename of parameter-file

-parameterset: if this option is specified, e.g. "-parameterset abc", the parameters listed in this parameterset, e.g. between
 the lines "parameterset abc" and "end" overwrite the default parameters specified outside the parameterset. The user can mark at
 most one parameterset in the parameterfile as the default parameterset using an asterix: "parameterset* abc". This parameterset
 is taken as the default, if the option "-parameterset" is not provided. If no parameterset is marked as default and if no
 parameterset is selected via "-parameterset", all parameters in parametersets are ignored.

-logfile (default none) optional filename of an ascii-file for the screen output

-verbose (default n if logfile given, otherwise y): logical flag (y or n) specifying whether the log should be
 displayed on the screen


FILE FORMATS
====================================================================================================================

Simulation parameters
---------------------

Simulation parameters are specified in a parameter file in ascii format. Please see parameters.txt for details.


Initial conditions
------------------

ICs are provided in an ascii file using one line for each particles. Please see ics_example.txt for details.


Output data
-----------

The state (time, positions and velocities) of the simulation is stored at regularly spaced time-steps, spaced by the 
interval 'dtout' given in the parameter file. Each such time-step is called a snapshot. The 0th snapshot, contains the
initial conditions and the last snapshot contains the final status at the exact time specified by 'tfinal' in the parameter
file. The user can choose between three output formats via the parameter 'outputformat' in the parameter file. These formats
are described below. (If needed, see module_io.f90 for the Fortran code that writes the output files.)

1: Each snapshot is saved in an individual ascii file [output]/snapshot_######.txt, where [output] is the output path
   specified in the parameter file and ###### is the snapshot index. The first line of this file gives the total number of
   particles, the second line the simulation time and the following lines each contain 6 numbers representing the position
   and velocity of one particle. Hence this file, has 2+n lines.
   
2: Each snapshot is saved in an individual binary stream file [output]/snapshot_######.bin, where [output] is the output path
   specified in the parameter file and ###### is the snapshot index. This stream has the format
   n,t,x1,x2,x3,v1,v2,v3, where n (8-byte integer) is the total number of particles, t (8-byte real) is the simulation time,
   x1/x2/x3/v1/v2/v3 are all vectors of n elements (8-byte reals) giving the position and velocity components. Each such file
   has exactly 8*(2+6n) bytes.
   
3: All snapshots are saved in a single binary stream [output]/snapshot_all.bin with the format
   n, t,x1,x2,x3,v1,v2,v3, t,x1,x2,x3,v1,v2,v3, t,x1,x2,x3,v1,v2,v3, ...
   where the variables have the same meaning as above. This file has exactly 8*(1+(1+6n)*nsnapshots) bytes.
   
By setting the parameter 'kind' to 4, all the 8-byte output types are truncated to 4-bytes, reducing the file sizes by a factor 2.