15-859E Programming Assignment 1:
N-Body Simulation

Due Date: 11:59pm Mon. 5 Oct. 1998

Revision 4: 6 Oct. 98. Modified sections are "Requirements", "Tips", or are marked in bold.

In this assignment, you'll implement a two-dimensional hierarchical n-body simulator. The recommended algorithm is Barnes-Hut. Substantial code is being provided to get you started on graphics and user interface. This code is written in C++ and uses the OpenGL graphics library and the Xforms user interface library, so it shouldn't be too hard to compile on most UNIX and Linux machines; porting it to other operating systems or user interface libraries will take more work.

I strongly suggest you try to compile and run the starter code by Thursday 24 Sept. to help catch compiler and operating system difficulties early.

Compiling and linking

The starter code is in pubdir/src/nbody, where pubdir = /afs/cs/project/classes-ph/859E/pub . Take a look at it here. You'll need to make your own copy of these files elsewhere before you start modifying them. C++ code and headers use suffixes .cc and .hh, while C uses .c and .h . As of 9/22, I've tested it on SGI's only, but on other UNIX machines, changes to the Makefile will hopefully suffice to get it running. You can find public SGI machines in Wean 5205. On an SGI, run "make -f Makefile.sgi" to compile and link the program. On a Sun, use "make -f Makefile.sun". This should create the executable "nbody".

If you get an error message such as "don't know how to make /usr/include/X11/Xlib.h" then Xwindows (or some other library) is not in the same location on your machine as on the cluster machines for which the Makefiles were configured. First try "make -f Makefile.systype depend" to remake the dependency list at the end of the Makefile, and if that doesn't work, search around for the missing include files and change the Makefile appropriately. On a Sun, if you get "warning: file /usr/local/lib/libstdc++.so: section .stabstr: malformed...", don't worry about it; it's just a warning.

See pubdir/www/software.html for instructions on how to set up environment variables so you can link shared object (.so) files. Do this now.

Running the starter code

Assuming you've gotten it to compile, run "nbody" to get it started. Here's the user interface: The code is currently packed with printf's to help you learn how Xwindows mouse and keyboard events work, should you want to change that code. Once things are running you should probably comment out almost all of the printfs so they don't slow things down so much.

To facilitate testing and interchange of data between students, I added a parser for a simple "particle2" file format to nbody.cc on 2 Oct. The file format is described in the example file pubdir/src/nbody/orbit.p2. I also added the gravitational constant G to the World structure.

The user interface was implemented using the Xforms library (see pubdir/www/software.html for documentation and downloads for this and other libraries mentioned here). The layout for the user interface was set using the fdesign program described in the documentation. If you run "fdesign ui_form.fd" you can rearrange the user interface. Hitting "save" while in that program rewrites ui_form.c and ui_form.h .

Graphics is done using the OpenGL library. We're only doing 2-D graphics, so we could have done it all with Xlib, I suppose, but OpenGL is much cleaner than Xlib. Double buffering (definition) is used to make the redisplay smooth.

Event handling (mouse and keyboard input) is done using Xlib, the low level library for Xwindows.

The main program, nbody.cc, is written in C++, but stays away from the advanced features of the language. The main features of C++ used that are not present in C are:

The Vec2 class, which is used for 2-D points and vectors, comes from the Simple Vector Library (SVL). See the nice documentation for it at pubdir/www/software.html.



The following are tips, not requirements.

15-859, Hierarchical Methods for Simulation
Paul Heckbert