The guidelines on using Swarm-NG.

Obtaining the source code

Currently we do not have any binary packages available. You can obtain Swarm source codes in two different ways:

Download the stable version from download page
Checkout the latest development version from Git Repository using one of the following commands: \ if you are an SSH user and you have set-up SSH with Github, then use:
```
$ git clone  git@github.com:AstroGPU/swarm.git
```
if you have not set-up SSH or never used SSH with Github, use:
```
$ git clone https://github.com/AstroGPU/swarm.git
```
If you want to download the stable version from git, use one of these commands instead:
```
$ git clone -b stable  git@github.com:AstroGPU/swarm.git
```
Or
```
$ git clone -b stable https://github.com/AstroGPU/swarm.git
```
If you get an error message when trying to clone the stable branch, then you probably have an older version of git. In that case, you might try the following commands
```
$ git clone  git@github.com:AstroGPU/swarm.git
$ git checkout --track -b stable origin/stable
```

Pre-requisites

Minimum Hardware requirements:

64-bit CPU
2GB Memory
nVidia GPU with compute capabality 1.3 or above (GT200 and Fermi architectures; some features require compute capability 2.0)

Software Requirements:

64-bit Linux (tested on Ubuntu and RHEL)
Latest CUDA drivers (should match CUDA SDK)
CUDA Toolkit 3.2 or later
GCC 4.x (Refer to your CUDA Toolkit manual for the correct version of GCC)
Boost libraries 1.33 or later (including program_options, regex)
CMake 2.8 or later
Berkeley DB C++ library (including headers: db.h db_cxx.h)

NOTE: Although Berkeley DB C library is installed on most Linux systems, the C++ headers and library are not

usually installed. Please make sure the file db_cxx.h exists on your system. Use locate to find it. It is usually found in /usr/include/db_cxx.h.

Optional software dependencies:

Doxygen
CMake GUI (cmake-gui)
Console CMake (ccmake)

Python development requirements:

Boost Python module
Python 2.7 or later development headers
Python packages: bsddb3, psutil

WARNING: Boost Python module must be compiled against the same version of Python headers and libraries you are linking to the swarm library. A mismatch is very likely to happen on systems with two version of Python installed (2.x and 3.x); and would result in misleading symbol binding errors when you try to load the module with the Python interpreter.

Installing required packages on your system, here we take Ubuntu as an example:

Download and Install CUDA Toolkit SDK and CUDA Development Drivers for Ubuntu from CUDA Downloads

Install CMake:

sudo apt-get install cmake libboost-dev libboost-regex-dev libboost-program-options-dev libdb++-dev

For generating documentation and using the CMake graphical user interface, install doxygen and cmake-gui:
```
sudo apt-get install doxygen cmake-gui
```

Install Python:

sudo apt-get install libboost-python-dev python-dev python-bsddb3 python-psutil

Compilation

Compilation of Swarm comprises two steps - Configuration and Compilation. Swarm uses CMAKE system for both. The following instructions are for a quick build of Swarm. Build System describes more advanced configuration and compilation settings.

Configure your building environment

The configuration process allows you to adjust the default compiling options. There are three options to do CMAKE configuration: Command-line, Console, and GUI. Here we discuss Console approach. Command-line and GUI options are described in Build System.

Create a directory for make files and binaries - <build directory>
Change to the <build directory> and type this command:
```
ccmake <source directory>
```
ccmake command is a console user interface for CMAKE; <source directory> is the top directory of swarm.
Press "c" to configure. If there are errors, press "e" to go to the variable editing page and fix the indicated problem(s) and start over. You may need to set the following variables to their correct values for swarm to compile properly:
- Boost_INCLUDE_DIR : Path where Boost headers are installed. [/usr/include/]
- CUDA_TOOLKIT_ROOT_DIR : Path to the CUDA toolkit [/usr/local/cuda, /opt/cuda]
Once configuration succeeds without errors, press "e" to exit configuration page and then press "g" to generate the make files.

Configuring the GPU type

CUDA requires the code to be optimized for special compute capability. In Swarm there are three variables for configuring Compute Capability:

GENERATE_GT200 : devices with compute capability 1.3, incluse Gefore 200 series and Tesla 1000 series.
GENERATE_FERMI : devices with compute capability 2.0, Swarm is mostly tested and is optimized to work best for this category of devices, this includes Gefore 400 series and Tesla 2000 series.
GENERATE_KEPLER: devices with compute capability 3.0, although not tested thoroughly, these devices are backward compatible and Swarm can take advantage of more resources being available. includes Gefore 600 series.

For a complete list of compute capabilities, refer to https://developer.nvidia.com/cuda-gpus

It is possible to compile Swarm for a compute capability that is not included in this list. Just open the file cmake/variables.cmake and look for GENERATE_FERMI. Copy and paste the section and change the names and compute capabilities.

After fixing all the paths and other options, make sure to run cmake . in the build directory to rebuild the make files.

Compile swarm

To compile and build executables and libraries, type:
```
make 
```
It may take a while to compile CUDA files.
If you need documentation, use the following command to generate the whole set of documentation:
```
make doc 
```

test: Integration testing

Once compilation is done, you can test the installation using:

make test

See How to test swarm for more extensive testing and customizing the tests.

If you want to test the computational capacity of your system, do:

make benchmark

WARNING:* This requires performing long integrations on both the CPU and GPU, so it may take a long time. Please be patient.

Please report your results at http://www.astro.ufl.edu/~eford/code/swarm/submit_benchmark.html

Feedback

If for any reasons the compilation does not work or the tests do not pass, please use the following command to generate a feedback package.

From the build directory (for simple installs it is the same as swarm directory) run

cd <build directory>
sh <source direcotry>/scripts/make_feedback.sh

The script will create a file named feedback.tgz. Email us this file with the description of your system so we can work towards fixing the problem.

If you examine the code and you find a bug, please don't hesitate to report it at http://github.com/AstroGPU/swarm/issues . Feel free to fork the repository and send pull requests if you fix any bugs.