bin <1> docs <2> integrators <3> reference <4> run <5> scripts <6> src <7> test <8> test-outputs <9>
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.
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.
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] for an overview of key points or read build_system.html for even more info.
Do a few quick tests with make test. See [Testing] 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).
src/tutorials/swarm_tutorial_cpu.cpp: uses swarm library with CPU)
src/tutorials/swarm_tutorial_gpu.cpp: uses swarm library with GPU
src/tutorials/swarm_tutorial_compare.cpp: compares results from GPU & CPU
src/tutorials/swarm_tutorial_benchmark.cpp: compares performance using GPU & CPU
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:
Read for_developers.html for an overview of how to write your own programs which build on Swarm-NG functionality.
Read eventlog.html and snapshotting.html for info on using the swarm output system.
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)
Asciidoc & Doxygen (if you want to generate html documentation)
Anything else?
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'.
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
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.
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.
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
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
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.
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>
bin contains executables (generated by 'make')
docs contains documentation for library and demo progarms ('make doc-asciidoc' generates html version of this documentation)
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).
reference contains reference manual (generated by 'make doc-doxygen' or 'make doc')
run is where swarm is intended to be run from. It also contains example configuration files.
scripts contains scripts used by the build process.
src contains the source code for the swarm library, as well as demonstration programs (e.g., tutorials/*.cpp, scatter_demo/swarm_scatter_demo.cpp)
test contains scripts and data files to test your installation of the swarm libaray and demo programs.
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.
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.
Visit the Swarm-NG Website.
Complete the Swarm-NG User Questionnaire
Download, install and user Swarm-NG code (via link above)
Read the archives of the Swarm-NG mailing list at the Google Group for Swarm-NG.
Join the Google Group for Swarm-NG to sign up for announcements via the Swarm-NG mailing list.
Contact Swarm-NG developers via the Swarm-NG mailing list.
Swarm-NG v0.1 may be licensed under the GPL v3, avaliable here.
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.
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:
the nVidia CUDA SDK,
the GNU Science Library,
Sverre Aarseth’s hermit2 code, and
John Chamber’s Mercury code,
which builds on a long history of n-body integrators, including Hal
Levison and Martin Duncan’s
Swift code.
We are happy to acknowledge financial support from:
the University of Florida’s Research Opportunity Seed Fund,
the National Science Foundation (grant CCF-0728797),
NASA’s Hubble Fellowship program, and
especially NASA’s Applied Information Systems Research Program (grant NNX09AM41G).
We also acknowledge additional support from:
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.