pkdgrav3
			 September 28, 2016
		      http://www.pkdgrav.org/

		 Doug Potter <dpotter@physik.uzh.ch>
		Joachim Stadel <stadel@physik.uzh.ch>

Quick Start
-----------

To compile the code, simply run:

    ./configure
    make

This will build a single executable:

    pkdgrav3_mpi      Version that uses MPI and pthreads (optionally CUDA)

Prerequisites
-------------

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/

    pkdgrav3 will locate the GSL installation by invoking gsl-config, so make
    sure that it is in your PATH.

FFTW - Fast Fourier Transform Library (optional)

    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/

CUDA

    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

Configuration
-------------

There are several flags to configure that affect the features and performance 
of pkdgrav3.  Flags are selected by adding them to the configure command, for
example, to request that more detailed instrumentation be performed:

    ./configure --with-fftw

For a list of all options to configure, use --help as in:

    ./configure --help

QUICK START: Cosmological Simulations

    ./configure --with-fftw --enable-integer-positions

    This will generate pkdgrav3_mpi with support for Initial Condition
    generation (FFTW is required), and optimized memory (Integerized postitions).

QUICK START: Cosmological Simulations with CUDA support

    ./configure --with-fftw --enable-integer-positions --with-cuda

    This builds pkdgrav3_mpi with GPU support.

Compiler options:

    pkdgrav3 has been testing and works well with the GNU Compiler Collection
    as well as the Intel Compilers. Selection of compilers is system dependent,
    and by default pkdgrav3 will look for "cc", "gcc", and "mpicc". It is possible
    to override this on the configure command line with "CC=" and "CXX=",
    for example:

    ./configure CC=icc CXX=icpc

Cray Systems

    For Cray systems, the compilers are choosen by selecting the appropriate
    "PrgEnv" and the default is often PrgEnv-cray, the Cray compiler suite.
    To switch use "module swap":

    module swap PrgEnv-cray PrgEnv-gnu

    The gsl and fftw libraries can often be selected with:

    module load fftw gsl

The following are the available options.

    --disable-simd

    By default, SIMD (single instruction, multiple data) instructions are
    enabled.  SIMD is supported for Intel (SSE/SSE2) and IBM (Altivec)
    architectures.  This gives a noticable performance boost for machines
    on which it is supported.

    --disable-instrument

    This turnes off detailed timing information for the various phases of
    computation and communication.  It uses the Matteo Frigo "cycle.h"
    for access to high resolution hardware timers.  By default, this
    feature is enabled on those architectures on which it is supported.

Build
-----

Once the configure script has been run to produce a Makefile and config.h,
the "make" command is used to build the program, as in:

    make

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:

    make -j 16

Running
-------

    pkdgrav3_mpi
    -------------
    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:

	mpiexec pkdgrav3_mpi simfile.par

    Consult your cluster documentation on how to run MPI programs.