COMP 599 - Winter 2010 - Assignment 1
Mass-Spring Particle System

Due 23:39 pm Tuesday January 26

Getting Started

Since this is the first assignment, you'll need to spend a little bit of time to get set up. If you are not already using Java then download and install the latest Java SE JDK (careful not to select the JRE). I also recommend using Eclipse as a development environment. Note also that the specification of this assignment is long in that this first assignment. Future assignments will be much shorter and you will be expected to complete them with more autonomy.

New to Eclipse?

If you are familiar with Eclipse (i.e., you took COMP 557 last term), then you can probably skip this section. For those of you who are new, here is a few extra tips on using Eclipse and getting set up.

Eclipse uses a workspace to organize your projects. When you start eclipse for the first time, it will make you a workspace in some default location (probably your home directory), but you can switch workspaces with the file menu, and open any folder you want for your workspace. One nice way to organize this would be to create a workspaceComp599 folder in your home directory, then tell eclipse to open that workspace.

Once your workspace is open, add a new java project, give it a name like A1. The defaults for the project when you click next are probably fine, e.g., default JRE, separate folders for source and class files. Once it is created, you'll see a src folder for the source files and bin for the class files (note that you'll eventually need to create a directory called "stills" for when you're recording images to make a movie).

You'll want to put the provided code (see below) in src folder of your new project, and there are lots of ways to do this, but you need the directory structure to match the package structure!! An easy way is to copy the comp599 directory in the zip file and paste it into the src directory. Since everything lives in the package comp599 you need this folder (i.e., you can't just copy and paste the a1 folder into src). If you copy files into your project on the file system side, you'll need to tell Eclipse to refresh its view of the project (right click on the project and select refresh). So that summarizes the steps for "dumping the source code into a project". You'll have lots of errors at this point, but they all go away when you attach the jars as specified in the assignment.

Lastly a few tips on using eclipse when you're browsing the code. If you let your mouse hover over an identifier, variable or method, a window will pop up telling you what it is, and providing you with the javadoc. If you hold ctrl and click on an identifier, it will take you to its definition (e.g., the implementation of a method). This is a great way to explore code rapidly! Note the yellow forward and back buttons on the tool bar are useful for going back to where you were after control clicking an identifier.

Sample Code

Download the provided code and dump it into a new java project. The code has two parts. The first part is the comp599.a1 package which contains the template code for this assignment. The second part is the comp599.tools package, which is a set of tools for quickly getting started with 2D and 3D graphics. There are three parts to the tools package:
  • parameters contains boolean and double parameter classes for quickly setting values with swing interface controls.
  • swing contains layout helpers and panels for quickly throwing together a Java swing interface.
  • viewer contains some simple classes for 2D and 3D viewing, including a 3D trackball and camera controls. (note that for simplicity, this assignment is set up to be all 2D graphics).

You do not need to change anything in the tools package to complete this assignment. The source for the tools is provided only for your convenience, and you should focus your attention on the a1 package. Do not change any of the package names as this will interfere with marking.

Jars and Native Libraries

The code uses two libraries: JOGL for OpenGL bindings, and vecmath for classes useful for math with 2D (and 3D) vectors.

The vecmath package is available as part of Java3D. Instead of installing the full Java3D, download this copy of vecmath.jar. Compared to the latest version, I believe this version is only missing a few setter and getters in the matrix classes (nothing that you will miss, and marking problems will be avoided). Also, the source code (i.e., the javadoc) is in the jar, so if it isn't automatically attached, you'll want to follow the following process. First add the jar to your build path, then open up Reference Libraries in your project, right click on the jar to set properties, go to source code attachment, and tell it where to find the zip file. You might also want to browse the vecmath javadoc online to become more familiar with the available classes and methods.

The JOGL bindings project has moved and is now available at Project Kenai. From the main page you can find the necessary downloads from the archived builds link, but note that you do not want the JOGL2.0 beta builds as there are some small but significant changes to methods. Here is a direct link to the latest release build, JSR-231 1.1.1a. Be sure to download the appropriate files for your platform. If on windows, download

  • jogl-1.1.1a-windows-i586.zip
  • jogl-1.1.1a-src.zip (to have access to javadoc in Eclipse)
  • jogl-1.1.1a-docs.zip (if you prefer reading javadoc in your browser)

To make your life more pleasant in Eclipse, you want to attach the source code to the jar for the javadoc, as described above.

Note that the .dll (or .so) that comes with the jar must be in your path. You can do this by opening the reference libraries in your project, right clicking to select properties, choose Native Library and enter the location of the .dll or .so file.

Note that the most noticable change to OpenGL function signatures under java is how functions with pointer arguments are mapped to two parameters under java (one for the array, one for the offset). See the note on Mapping of Pointer Arguments and Index Parameter for Arrays in the JSR 231 Specification Overview.

There will not be extensive OpenGL programing in this assignment, but if you need either a quick introduction to or to brush up on OpenGL, check out these links: The OpenGL Programming Guide (The Red Book) online version (or at Amazon), Jumping into JOGL, JOGL: A Beginner's Guide and Tutorial. Another popular resource is nehe.gamedev.net (see the NeHeGL JOGL link on the bottom left).

Creating Videos

Below you are asked to assemble a sequence of recorded frames that demonstrate the required features of your program. Everyone should use the xvid MPEG-4 / H.264 codec. Video creation is straightforward under windows using virtualdub. If you are using Linux or OSX, a good alternative is to use mencoder on the command line (you can do this on windows too). See the MPlayer page for downloads and more information, and you can probably make your video with a command line that looks something like the following:

mencoder -ovc xvid -xvidencopts bitrate=1800000:me_quality=6 -fps 24 -o out.avi mf://img
Alternatively, under windows, once you have both the codec and virtualdub installed, you can create an avi file from a sequence of png still frames using the following steps (you'll probably want to complete at least part of the assignment and then come back to these steps later).

  1. In virtualdub, select "Open video file..." from the File menu and choose the first image in the sequence (i.e., img00000.png). This will automatically load the entire sequence
  2. The loaded images probably do not have a width and height which are multiple of 16, so you'll need to add a filter. Under the Video menu, select "Filters...", click Add, select Resize and click OK.
  3. In the window that opens, there should be an option for Codec-friendly sizing in the bottom right. Select "Multiples of 16" and click OK. Now back at the Filters, click OK to close it.
  4. Now you need to set the codec. Choose "Compression..." under the video menu and choose the codec you installed (e.g., Xvid MPEG-4 Codec).
  5. The default configuration of the codec should be fine, but I would prefer that you use maximum quality settings (i.e., adjust the quantization). It is unlikely that any of the files you are creating will be too large, but use your best judgment!
  6. Now you can save the image sequence to an avi file. Select "Save as avi..." under the file menu and specify the file name, then wait for virtualdub to finish encoding the file (it might need a minute depending on the length of your video and the speed of your computer).

Note that there are also many other good ways to encode videos. Do whatever is easiest for you, but make sure that the result is high quality and uses the xvid codec.

Steps and Objectives (8/10)

The provided source code should help you get started quickly. It has an interface for creating points and dragging them around. The controls window lets to create a few different procedurally created test systems and lets you adjust parameters stuff as stiffness, damping, and step size. The main method lives in the A1App class, so this is the one you'll want to start when running your program. Note also the keyboard commands attached to the drawing canvas that let you start and stop the simulation, reset, and clear. There are also controls to help you save sequences of png files. The important parts of the program, however, are missing. Note also that you will not be able to test much until you complete the first three steps.

  1. Spring Forces

    Finish implementing the code that computes spring deformation and viscous spring damping forces. See the Spring.java file and the comment the starts with "TODO". Refer to your class notes or the PBM notes on the Pixar site. You can optionally add viscous damping too, but it should be left at zero in your demonstration videos.

  2. Numerical Integration

    Create getState and setState methods to get and set phase space state of the system in a flat array. Use these methods to write a forward Euler numerical integration method using the Integrator and Function interfaces provided. See the "TODO" comments in ParticleSystem.java in the updateParticles and derivs methods. Also see the "TODO" comment in the ForwardEuler class in the numerical package.

    To elaborate on this a bit, the step method in integrator needs flat array containing the phase space state of the system. But the state of the system is contained in member variables of all the instances of the particles. As such, you'll want to write a method such as getState(double[] y) in your particle system class to pack up all the positions and velocities of the particles. The setState method should obviously do the opposite, so you can take the double[] yout array result from calling step. Of course, you'll also need to allocate yourself arrays of the appropriate size so you can use these methods, and so you can call step. Note that the number of particles will increase if you click to create them, so you'll probably want to do something smart, like grow the size of your arrays as needed. So, what you want to do is, first check if you have arrays y and yout that are of an appropriate size for the current number of particles. Then pack the state of the particles using your getState method. Then call the step method of the integrator. Then unpack the result into your particles with your setState method.

  3. Pinned Particles

    Some of the example systems have particles with a pinned property set to true. Add a method to filter the state (and forces) so that these simple constraints work nicely with your numerical integration methods (both forward Euler, and those in step 5).

  4. To elaborate on this slightly, if a particle is pinned (a bilateral constraint), then each coordinate of the particle needs to remain constant. It should also have zero velocity and it should not undergo any acceleration. Your derivs function needs to make sure that the velocity and acceleration are valid, otherwise strange things might happen! Suppose you let forces produce accelerations, and you integrate these to get velocities. You'll accumulate velocities for the particle, which will try to make it move at each step, but you'll set the position back to where it is supposed to be. But that wrong velocity that the particle has will affect damping forces on the particles to which it is attached by springs! Thus, it is best to make sure that the whole state makes sense with respect to the constraints.

  5. Particle Wall Contact

    Modify the method you made in the previous step to also keep particles inside the window by projecting them to the closest boundary. For a particle in contact with a wall, a velocity away from the wall is OK, but a velocity toward the wall should not be allowed (the same for forces).

  6. Additional Numerical Integration Types

    Create classes that implement the Integrator interface for the midpoint method, the 2/3 point method, and the fourth-order Runge-Kutta method. That is, add classes to the numerical package and use them in your particle system. You should also implement the symplectic Euler method, but note that this will break the abstraction of the Integrator interface slightly in that you will need to know how the positions and velocities are packed in the state array.

  7. Keyboard Controls

    Add keyboard controls so that you can switch between integrators by pressing 1 through 4 (have a look at the "TODO" comment at the bottom of the A1App class which adds the KeyAdapter to the canvas).

    When adjustSubsteps is true, you should automatically adjust the number of sub-steps so that each step involves the same amount of work (i.e., number of calls to compute derivatives). That is, 4 for FE, 2 for midpoint, 2 for 2/3 point, 1 for RK4. You might try to find scenarios for spring and damping parameters where different methods will perform better given the same computational cost.

  8. Stability Movie

    Record a sequence of examples that demonstrate how these different numerical methods perform. Specifically, with the damping set to zero find a step size which demonstrates which method performs best. Also demonstrate what happens and which is best when the damping is not zero (you might want to do the written question and think about regions of stability when doing this question. Keep the time steps fixed. Encode the video as described above. Please keep your video short (half a minute should be plenty) and use the comment area to describe what you are showing.
  9. Interesting Movie

    Finally record a sequence of something interesting or amusing. This could be something within the existing functionality of the specification and provided code, or some additional feature you add to your code (e.g., particles with other properties such as colours, different bouncyness properties). Be creative, but don't spend too long on anything as the assignment is quite long as it is. Encode the video as described above. Keep your video short and to the point (i.e., at most a few MB).

Written Questions (2/10)

Consider a one dimensional system consisting of a single particle with mass 1 kg attached to a rigid wall with a spring (100 N/m).

  1. If the particle starts with zero velocity at a position 0.01 m from rest (x=0), what is the exact trajectory? What is the frequency of the oscillation in Hertz?

  2. Given what you know (from class) about the stability of the different integrators used in the programming part of this assignment, what would be a good choice of step size for each integrator? Use your implementation to check that it matches what you expect from the theory.

  3. In the case of forward Euler and given a step size of 0.05 s, what is the minimum amount of damping required to prevent the system from blowing up?

  4. Again, in the case of forward Euler and given a step size of 0.05 s, What is the maximum amount of damping that can be used without the system blowing up? Use your implementation to check that it matches what you expect from the theory.

Prepare a pdf file with your answer to these written questions (scanned hand written document, or generated with latex, openoffice, or otherwise) and submit it along with your assignment via webCT.

Finished?

Great! Submit your source code and two xvid encoded videos as a zip file via webCT. Include a readme.txt file with any specific comments. Also be sure to include a pdf with your written answer (i.e., scans of handwritten work, or typeset). Your readme should provide a list of people with which you discussed the assignment, or state that you did discuss the assignment with anyone.