CS 5643 Assignment #1: Position Based Fluids

Professor: Doug James
Due date: Monday, March 2, 2015 (midnight)

In this first assignment, you will implement a particle-based fluid simulator related to smoothed particle hydrodynamics (SPH).  Your implementation will be based on the recent "Position Based Fluids" (PBF) approach described in [Macklin and Muller 2013]. You will extend a simple starter-code implementation to support the basic PBF functionality, then extend it to produce a nontrivial animation/simulation of your choosing.

Groups: Work on your own, or in a group of at most two people. Additional work is expected from a group submission, such as a more elaborate creative artifact or modeled phenomena. PhD students are encouraged to work alone, and pursue a more challenging creative artifact. You can use the Piazza group-finding feature if you are not sure who is also looking for partners.

Starter Code (cs5643.particles): This project has starter code (available to registered students through CMS), primarily to support basic OpenGL rendering and a simple Swing GUI. Online Javadoc documentation here. In this assignment, you will modify this package as needed.

Software Dependencies:  The starter code will compile and run using JDK 1.5 or later. In addition to Java, the starter code also uses two other libraries that you need to install/get: 
Starter code tips:

  • Search for 'TODO's to find places in the code where you should implement better functionality. Some of these aren't essential to the program, but may make your life easier; these are marked as 'optional'.
  • Most of the action happens in ParticleSystemBuilder.java . This includes setup, GUI interactions, and timestepping. If you want to change something about the way the application runs, this is the first place to look.
  • By default, the simulation will perform several time steps per frame. Use the '-' and '=' keys to adjust the number of steps per frame as the program is running. Once you have implemented a better integrator (in ParticleSystem.java), you might choose to step once per frame, as fluid calculations can be very slow.
  • You can save the result of your simulation by pressing 'e' as the simulation runs. This creates a new FrameExporter (defined as a subclass of ParticleSystemBuilder) which will write the positions of each particle to a file every frame. You can use the provided python script (makeMitsubaFile.py) to import these files into Mitsuba to generate higher quality renderings. The default rendering format is simply diffuse particles, with hard shadows as shown here:

  • Within ParticleSystemBuilder, there is an abstract Task class that you may implement to add various GUI modes (e.g. adding particles, moving particles around, selecting particles and printing various stats about their current state, etc.) A simple CreateParticleTask has been included as an example. Switch between Tasks by adding new buttons in BuilderGUI.

  • Do I have to use the starter code? Can I program in C++? etc.: The starter code is provided to make your job easier, however you are not required to use it. Feel free to implement your assignment in any language or programming environment that you want (C++, processing, python, etc.). However you are still expected to implement the assignment steps listed below, and answer the questions. You may not use extensive libraries for particle systems or simulation since you are expected to implement the functionality from scratch (that's the point and the fun of it). However, please feel free to use any third-party graphics or 3D rendering software that you want.

    Assignment Steps: The code provides some very basic functionality for a particle system, but does not implement any fluid-like forces, nor container boundary conditions to keep the particles from flying away.
    After you get the basic simulator working, you should try something unique to your submission:
    Hand-in using CMS:  
    Start early. Ask questions. Have fun!!! 

    On collaboration and academic integrity: You are allowed to collaborate on the assignments to the extent of formulating ideas as a group, and derivation of physical equations. However, you must conduct your programming and write up completely on your own (or with your partner), and understand what you are writing.Please also list the names of everyone that you discussed the assignment with.  (You are expected to maintain the utmost level of academic integrity in the course. Any violation of the code of academic integrity will be penalized severely.)