Skip to content

Old ReadME

Jump to bottom
salehqt edited this page Jan 10, 2012 · 1 revision

README for Swarm-NG

Swarm-NG v0.1.3 (c) Swarm-NG Development Team 2010

Introduction

What is Swarm-NG?

The Swarm-NG package helps scientists and engineers harness the power of GPUs. In the early releases, Swarm-NG will focus on the integration of an ensemble of N-body systems evolving under Newtonian gravity. Swarm-NG does not replicate existing libraries that calculate forces for large-N systems on GPUs, but rather focuses on integrating an ensemble of many systems where N is small. This is of particular interest for astronomers who study the chaotic evolution of planetary systems. In the long term, we hope Swarm-NG will allow for the efficient parallel integration of user-defined systems of ordinary differential equations.

What is included in May 5, 2010 release of Swarm-NG 0.1.3?

This initial release contains GPU-based integrators for few-body systems (hermite_gpu, hermite_cpu, verlet_gpu, verlet_cpu). It comes with a basic, easy-to-use public interface for setting initial conditions, calling the GPU-based integration algorithms and accessing the output data. Small example programs are provided to demonstrate functionality and how to program with Swarm-NG.

Quick Start Tips

  • Download the swarm-NG library from http://www.astro.ufl.edu/~eford/code/swarm/download.html

  • Build the library and example programs with make. See Building the Swarm-NG Libraries and Demo Programs for an overview of key points or read build_system.html for even more info.

  • Do a few quick tests with make test. See How do I test Swarm-NG? for more info.

  • To check the speedup on your system , run make benchmark. (Warning: This requires performing the integrations on both the CPU and GPU, so it can take a long time. Please be patient.) Report your results at http://www.astro.ufl.edu/~eford/code/swarm/submit_benchmark.html

  • Read some online documentation (text version in docs subdirectory).

  • Browse the online reference manual. (You can generate a local copy with 'make doc').

  • To see how an end user can use swarm as is:

    • Take a look at the test test/swarm/swarm-run.test. If you ran make test successfully, then the output will be stored in test-outputs/swarm/swarm-run.test/output.log

    • Read swarm.html and configuration_file.html for a description of swarm, the configuration file format and valid parameters for the bin/swarm program. (Some of the other demos use a configuration file with the same format, but they may not accept all the parameters.)

    • To see how end users can access data written by the swarm logging system, use swarmquery output_file or swarmquerykeplerian output_file. For info on options, run swarmquery --help or swarmquerykeplerian --help.

  • To learn how to access the Swarm-NG library from you own code, work through the series of introductory tutorials in src/tutorials (in the following order).

    1. src/tutorials/swarm_tutorial_cpu.cpp: uses swarm library with CPU)

    2. src/tutorials/swarm_tutorial_gpu.cpp: uses swarm library with GPU

    3. src/tutorials/swarm_tutorial_compare.cpp: compares results from GPU & CPU

    4. src/tutorials/swarm_tutorial_benchmark.cpp: compares performance using GPU & CPU

    5. src/tutorials/swarm_tutorial_montecarlo.cpp: performs many n-body integrations in Monte Carlo fashion in user-specified region of parameter space. This program uses a configuration file. The format is described in swarm_tutorial_montecarlo.html.

  • To learn more from examples of non-trivial codes, take a look at the following applications:

    • src/scatter_demo/swarm_scatter_demo.cpp: example that considers the effect of passing stars on planetary system. More Info at swarm_scatter_demo.html

    • 'src/swarm.cpp: this reads in an ensemble of initial conditions and writes output to binary files. More information at swarm.html.

    • The binary output files can be easily accessed via the swarmquery program (see swarmquery.html or swarmquerykeplerian.html).

  • To learn more about how developers an use the swarm library:

Building the Swarm-NG Libraries and Demo Programs

What hardware & software is required to build & run Swarm-NG?

  • Hardware

    • Linux-based workstation with 64-bit kernel (32-bit kernels might work but have not been tested; certain kernel versions?)

    • nVidia GPU with GT200 chip (we intend to support Fermi in near future) (there are some issues with swarmlog and G80’s that may be resolved in the future)

  • Software

    • CUDA v2.3 and/or v3.0 (must compile with -arch=sm_13)

    • g++ v4.3 (CUDA does not yet work with 4.4+)

    • Boost++ v 1.33-1.41 (headers, regex library, and program_options libraries; e.g., pacakges libboost1.40-dev liboost-regex1.40-dev libboost-program-options1.40-dev) (something changed in 1.42 which will require minor modifications to swarm)

    • GNU Science Library (GSL)

    • Asciidoc & Doxygen (if you want to generate html documentation)

    • Anything else?

How do I build Swarm-NG for Linux?

Run make. Users can specify the paths to compiler, libraries, and include files, as well as compiler flags in the file 'Makefile.user'. This file does not exist, but can be easily added. For example, to change the path to your CUDA installation, add the line like 'CUDAPATH?=/usr/local/cuda' to Makefile.user. For other variables that can be overridden, see the file 'Makefile'.

How do I build Swarm-NG for Windows?

While we do not intend to support Swarm-NG for Windows, we can pass along some of the following tips.

  • We’re told that following build environments for nvcc work on Windows using the The Microsoft Visual Studio compiler, cl, as the host compiler:

    • Windows DOS shell

    • Windows CygWin shells, use nvcc’s drive prefix options.

    • Windows MinGW shells, use nvcc’s drive prefix options.

  • Although a variety of POSIX style shells is supported on Windows, nvcc will still assume the Microsoft Visual Studio compiler for host compilation. Use of gcc is not supported on Windows.

  • You can find more information from /usr/local/cuda/doc/nvcc_3.0.pdf

How do I test Swarm-NG?

make test

In the current release, small differences in floating point values can result in failures that are inconsequential. So if the failures occur, please take a look at the output file indicated to check whether the difference is significant.

If so and you can not solve the problem, then run make feedback, which will generate a file named feedback.tgz which we may request that you send the developers.

Demo Programs

Commands to run demo codes

First, build the tutorials and demos with make. Then, you can run the following demos from the tutorial.

  • swarm_tutorial_cpu: run bin/swarm_tutorial_cpu

  • swarm_tutorial_gpu: run bin/swarm_tutorial_gpu

  • swarm_tutorial_compare: run bin/swarm_tutorial_compare

  • swarm_tutorial_benchmark: run bin/swarm_tutorial_benchmark. Several options are avaliable. run with the command line option --help for more info.

  • swarm_tutorial_montecarlo: change into the run sub-directory and run ../bin/swarm_tutorial_montecarlo integrator-tutorial_montecarlo.cfg The behavior of this tutorial can be easily adjusted by changing the configuration file. See swarm_tutorial_montecarlo.html for details.

  • swarm_scatter_demo: This requires multiple input files. See swarm_scatter_demo.html for details.

Known Limitations and/or Bugs

  • swarm is limited to N-body systems with 3-10 bodies.

  • Integrations that result in an output file size comparable to half the system memory or more will likely crash.

  • swarm only integrates forward in time.

  • While there are euler, rk4 and rkck integrators, they are in a preliminary form and should not be used.

  • E.g., rk4 requires exactly 3 bodies and does not include a cpu version

  • We have not tested Swarm-NG with a 32-bit OS

  • If you’ve previously run a v0.1.1 or v0.1.2 of swarm-NG on a machine, please reboot it before proceeding.

  • For an updated list, visit the Swarm-NG Website

What should I do if I think I found a compile-time bug?

  • Please first check that you can successfully run make test. If this fails, then please double check that you have the required drivers, libraries installed and paths set correctly. You may need to create a Makefile.user to specify the path to your compilers, libraries, include files. You may also need to specify the path to your cuda libraries via LD_LIBRARY_PATH.

  • If the error arises while compiling the included tests, then run make feedback, which will generate a file named feedback.tgz which we may request that you send us.

  • Otherwise, please identify the minimal amount of code that produces the compiler error.

  • Contact Swarm-NG developers via the Swarm-NG mailing list

What should I do if I think I found a run-time bug?

Unfortunately, GPUs can sometime get stuck in a problematic state, particularly during code development and when not running in console mode. Before reporting a runtime bug, please test the code immediately after reboot your system into console mode.

If the problem persists, then please check the archives of the Swarm-NG mailing list at the Google Group for Swarm-NG to see if the bug has already been discussed.

If not, then please contact Swarm-NG developers via the Swarm-NG mailing list.

Organization of Swarm-NG

Swarm-NG uses the following directories:

bin (1)
docs (2)
integrators (3)
reference (4)
run (5)
scripts (6)
src (7)
test (8)
test-outputs (9)

  1. bin contains executables (generated by 'make')

  2. docs contains documentation for library and demo progarms ('make doc-asciidoc' generates html version of this documentation)

  3. integrators each subdirectory contains the code for a single integrator (e.g., hermite_gpu, hermite_cpu, …​). The first release contains a few working integrators, (e.g., hermite_gpu and hermite_cpu) and a few that are still in development (e.g., hermite_adap_gpu, rk4, rkck, euler).

  4. reference contains reference manual (generated by 'make doc-doxygen' or 'make doc')

  5. run is where swarm is intended to be run from. It also contains example configuration files.

  6. scripts contains scripts used by the build process.

  7. src contains the source code for the swarm library, as well as demonstration programs (e.g., tutorials/*.cpp, scatter_demo/swarm_scatter_demo.cpp)

  8. test contains scripts and data files to test your installation of the swarm libaray and demo programs.

  9. test-outputs contains results of tests (generated by 'make test')

For more information on the organization of directories and files, see organization.html and/or the doxygen files page.

Digging Deeper

Where can I find additional documentation?

There is additional documentation for various components of Swarm-NG in the docs subdirectory. Most are written in asciidoc format. To generate the html versions, run make doc-asciidoc. Or view the online documentation.

After running make doc-doxygen, you can also browse the doxygen reference manual.

As the library interface solidifies, we anticipate providing additional documentation in future releases and/or at the Swarm-NG Website

In the mean time, you may want to browse the archives of the Swarm-NG mailing list at the Google Group for Swarm-NG.

How can I learn more about and/or contribute to the the Swarm-NG project?

Licensing, Citing, Acknowledgements

Licensing Information

Swarm-NG v0.1 may be licensed under the GPL v3, avaliable here.

Acknowledging use of Swarm-NG

When writing papers which made use of Swarm-NG, we strongly encourage you to cite the technical paper describing Swarm-NG. We will provide a citation as soon as a preprint of this paper is avaliable. In the mean time, please mention the Swarm-NG Website.

Acknowledgements

Swarm-NG is the product of a collaboration between astrophysicists (UF Astronomy department and Harvard-Smithsonian Center for Astrophysics) and UF computer scientists at Prof. Jorg Peters' SurfLab. Contributors to the Swarm-NG codebase include: Eric Ford, Ameya Gancchha, Jianwei Gao, Mario Juric and Young In Yeo.

The Swarm-NG library includes code reused or adapted from:

We are happy to acknowledge financial support from:

We also acknowledge additional support from:

COPYING

Copyright (C) 2010 Eric B. Ford and the Swarm-NG Development Team
Free use of this software is granted under the terms of the GNU General Public License (GPL) v3, which should be included as gpl-3.0.txt and also avaliable online.

Clone this wiki locally