====== pkdgrav3 ======

<code>
               pkdgrav3
         September 24, 2018
          http://www.pkdgrav.org/

    Douglas Potter <douglas.potter@uzh.ch>
    Joachim Stadel <stadel@physik.uzh.ch>
</code>

====Quick Start====

  * The pkdgrav3 code now uses the "cmake" build system. It is recommended to use an "out of source" build. The easiest way to accomplish this is to create a subdirectory in the pkdgrav3 source directory:

<code>
mkdir build
cd build
cmake ..
make
</code>

This will build a single executable "pkdgrav3" and other utility programs.

=====Prerequisites====

CMake - cmake build system

Most modern systems already have cmake installed. Pkdgrav3 requires
version 3.1 or newer of cmake. You can check with "cmake --version":

<code>
    pkdgrav3:~> cmake --version
    cmake version 3.5.2
</code>

  * If you need a more recent version is can be found at:

[[ https://cmake.org/|CMAKE HOME ]]
    
==== GSL - The GNU Scientific Library ====

This library is usually available on HPC systems, but if not it must be
downloaded and compiled, and can be found at this URL.

[[ https://www.gnu.org/software/gsl/|GSL ]]

pkdgrav3 will locate the GSL installation by invoking gsl-config, so make
sure that it is in your PATH. Alternatively, you can tell CMake where to
find it by defining GSL_ROOT_ROOT:

<code>
    cmake -DGSL_ROOT_DIR=/opt/gsl/2.5
</code>

==== FFTW - Fast Fourier Transform Library ==== 

If FFTW is available then two advanced features are enabled in pkdgrav3.
  * 1. Initial Condition Generation, and,
  * 2. Power spectrum measurement

If is is not available on your system it can be obtained from:

[[ http://www.fftw.org/|FFTW ]]

If CMake does not automatically find FFTW then you can define FFTW_ROOT:

<code>
    cmake -DFFTW_ROOT=/path/to/fftw
</code>    
    
==== CUDA (optional) ====

If your system has a CUDA capable GPU then pkdgrav3 can use it.
The necessary toolkits can be downloaded from nVidia.

[[ https://developer.nvidia.com/cuda-downloads|DOWNLOAD CUDA ]]

==== Configuration ====

Integer Positions

This option saves memory and provides sufficient accuracy for cosmological simulations.
Only periodic boxes are supported. Enable by setting INTEGER_POSITION when running cmake.

<code>
cmake -DINTEGER_POSITION=True ...
</code>

==== Potentials in Lightcone particle output ====

The potential for each particle can be output for the lightcone.
Enable by setting POTENTIAL_IN_LIGHTCONE when running cmake.

<code>
cmake -DPOTENTIAL_IN_LIGHTCONE=True ...
Build
</code>

Once CMake has been run to produce a Makefile and associated files, the "make" command is used to build the program, as in:

<code>
make
</code>

The build can be done in parallel so if you are on, for example, a 16 core machine, the build process can be sped up with:

<code>
make -j 16
Running
pkdgrav3
</code>
--------

This version is run using the MPI system on the cluster in question. Normally this involves a special command (often "mpirun" or "mpiexec"), for example:

<code>
mpiexec pkdgrav3 simfile.par
</code>

Consult your cluster documentation on how to run MPI programs.