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 (danail.obreschkow@icrar.org) 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.