CSSE 120 Final Python Project—Emergence

Project Requirements

Background

Many systems in real life are composed of a multitude of identical objects, each with simple behavior. However, as a whole, complicated or unexpected group behavior emerges. Consider traffic (automobile, or information packets on a computer network), a market economy, a school of fish, or an army of ants. Their behavior is called emergent behavior.

Emergence rules: Consider a group of creatures. They can be a flock of birds or a school of fish. In either case, each creature is only aware of its immediate surroundings. We can describe their behavior using three simple rules:

Avoid obstacles - if a creature is crowded by its neighbors (or by a fixed object), it tries to accelerate away.
Stay with the flock - accelerate toward the average location of neighboring creatures.
Match velocities - accelerate to attempt to fly in the same direction as neighboring creatures.

Note the liberal use of the word "accelerate". Don't forget that acceleration is a vector quantity. It can change both the magnitude (including a negative change, often called "deceleration") and direction of a creature's velocity. The main task of your program is to simulate the motion of the creatures and to calculate an acceleration for each simulation step that attempts to follow the (sometimes-conflicting) rules. In order to be realistic, each creature should have a maximum allowed acceleration magnitude. One important part of this problem is deciding how to deal with the situation where one or more of the rules indicate a need for an acceleration whose magnitude is greater than the maximum.

See the instructor's demo for some ideas. Here are some links to documents that you should read:

Here is a website showing some nice animations and images of emergent behavior. Note that yours could be similar, but you only need to consider 2 dimensions, not 3D!
Here is the original paper about a computer-generated flock of birds at a graphics conference in 1987! This document probably contains the most useful ideas about how to manage the acceleration.
The Wikipedia article on emergence is a great read on the concept of emergence, with many example applications.

Requirements

The final project for the Python part of this course is to implement Emergence, satisfying these core requirements.

You must have a group of creatures, which are displayed graphically. The window should be no larger than 1024 x 768 pixels, so it can be easily displayed to the class using the projector. zellegraphics should suffice for developing the GUI, but you are welcome to explore and use a different library like pygame if you wish.
Their motion must be affected by their neighbors using the three emergence rules. (You may add additional rules as an enhancement -see below).
You must use the rules to calculate a total acceleration for each creature, and its magnitude must be no larger than the creature's maximum acceleration. You may want to do some experiments in order to determine a reasonable maximum acceleration.
You must be able to interact with them in some way, either by introducing obstacles, or having them follow the mouse.
You should have a way of adjusting the relative weights of the three accelerations derived from the Emergence rules. This can be by changing the program code if you wish, but that should happen by simply changing the values of some variables that you define.
Your project must use a GUI for game play.
You must define some kind of new objects, using a dictionary for each object as we did with Card objects in Session 16.
All team members must contribute to their project and understand all of the code that their group submits. The instructor reserves the right to ask individuals about their understanding, and to adjust the grades of those individuals and/or the team accordingly. It is your responsibility to help your teammates understand the code that you write.

Much of your work on this project will be figuring out how to translate the emergence rules into a working design and implementation. If you are having trouble planning or getting started, get help. It is much better (and easier) to get help early and start off with a good plan than to try to hack a poor design into a semi-functional program in the final days before it is due.

Project Teams

Your project teams and repository information are available from this location. Each member of your team is advised to checkout your team repository at the start of the project. Before you edit code, documents, and other aspects of the project, you should update your local workspace, edit, update, then commit your work back to your repository. Using that cycle will minimize conflicts. Remember to provide appropriate commit messages and to do svn add if you want to add new files to your repository. Of course, don't forget to commit after you add new files.

Milestones

On Day 16, your team should determine what you expect to have done by the beginning of each subsequent class day! Each milestone will contribute to your overall project grade. Each milestone must be done before the specified class session unless specified otherwise. You should describe each milestone in terms of something that is testable, i.e., it should be something that the user of the program can see happening. For each milestone, you must commit your work to your team's repository and include a clear commit message stating that this milestone is completed. Your team's repository is named csse120-201020-teamXY, where X is your section number, and Y is your team number within that section.

Session 16 (before the end of the session) -- Checkout the project. The location of your team's repository is
http://svn.cs.rose-hulman.edu/repos/csse120-201020-teamXY

where X is your section number and Y is your team number as announced by your instructor.
The team should check out the Emergence project. In addition to main.py, the project contains a document that you can use for recording your milestones for each session. Each team member should independently add his or her name to the comments at the top of the main.py file. This involves each of you editing the file, so it requires careful use of SVN. Follow the steps below in one sitting. If you are interrupted during this process, repeat the steps:
1. Right-click main.py in the Pydev Package Explorer view. Choose Team→Update. This ensures that you have the most recent changes from your teammates.
2. Edit the comments in the file to add your name.
3. Save the file.
4. Right-click again on main.py in the Pydev Package Explorer view. Choose Team→Commit... This shares your change with your teammates.
Follow the SVN cycle of update-edit-update-commit whenever you make changes to your program. You should definitely commit your work after each milestone beginning with the milestone for session 17.

Before the end of class, you should read and understand the documents. You should figure out your Milestones (what is to be completed before each session), and record them on the Milestones document in your repository. You should do as much program design as you have time for. [In 201020, this may not be a lot of time, due to the convocation schedule.] Perhaps you should do a little coding.
Session 17 — One part of your Session 17 milestone should be completed design documents. You should show approximately what the screen will look like when your program runs; you should decide on the objects (dictionary types) you will need, and also some of the high level functions. Also document your calculation approach; how (mathematically) will you balance the three Emergence rules to calculate the acceleration? The rest of this Milestone is TBD by you in Session 16.
Session 18 — TBD by you in Session 16.
Session 19 — TBD by you in Session 16.
Session 20 — Game Finished, including possible enhancements (below). You will do a presentation, and you should update your design documents, and provide a project summary (more on that later).
Session 21 — Team Evaluation of Your Partners. This will be made available in ANGEL under Lessons.

Grading

Project grades will be based on both individual and group results. We will check off each project milestone, to make sure you are making steady progress. The final project program will be graded based on both the proper functioning of your program and an evaluation of your design, coding style, and documentation (including SVN commit messages).

Each team member will be required to complete an evaluation survey about his or her own performance and that of each of his or her teammates. We will use these surveys and our own observations to assign individual project grades. Individual grades will be based on your contributions to the project, how well you work with your teammates, and your understanding of all parts of your team's code. If is not obvious from our work with you that you understand the code, we may ask to meet with you before assigning a grade.

Suggestions

Plan first! Use top-down design. Get help early if you need it!
Investigate and decide on the mathematical aspects of the program very early.
Do your programming as a group, with one person driving and the other people looking on and making suggestions rather than splitting it up and working on it separately.
The person who is the best programmer should not be the usual driver. Of course we want your team to produce an excellent working program, but it is even more important that you all learn from doing it and that you all understand the code that you submit. If your teammates "leave you in the dust," ask them to slow down and explain things.

Enhancements

Once you are done with the basic version, you may want to add some enhancements for extra credit. You will earn a higher grade for doing more challenging ones, and the more, the better. Be creative. What's cool and challenges you? Discuss your ideas with your instructor.