CS106 Final Project

The final project in CS106 is an opportunity for you to showcase what you have learned in this class, and begin applying your newfound knowledge and abilities to a problem that interests you personally.

The final project is to be an individual or a small group project, although I hope that in either case you consult with others in the class and with professors (if possible) for help in design, implementation, and debugging.

Timeline (Milestones) ¶

There will be four deliverables for this project, due according to the following schedule:

1. Project Design (2%): You submit a document outlining what your project will do. See below for more details. Due W9 Saturday, end of day.

2. Project Walkthrough (3%): You and I meet to look at what you have completed. I will recommend solutions to problems you are having. At least 50% of your code must be complete when we meet. Sometime between Thanksgiving and Study Break.

3. Project Showcase (5%): during our final exam time you will demo your work to the class. You’ll mainly show your code running, but depending on the project you might also make slides. For a team project, each team member should contribute to the presentation.

4. Project Submission (90%): You submit your final project code by the end of the day of our final exam time. See details below. Since the problem-solving process is essential and cannot be evaluated on the basis of code alone, code submitted without a walkthrough will not be graded.

I will combine the points from these deliverables to compute your score for the final project/presentation.

Details for each milestone are below:

Milestone 1: Project Design ¶

Write a document (Word, PDF, etc., not Python code) that includes the following:

• A high-level description of the project.

• What might be the main challenges you’ll have to overcome for this project? What is your plan to tackle them?

• What might be some of the different pieces of the project that you can work on developing one at a time? Specifically:

  • What parts of the project could you get working first, to see if you’re on the right track?
  • How you might know whether each part is working?
  • What data will your project store? What data types will you use, and how? Sketch out a few examples of what the data might look like (e.g., the state of a game, the objects in a simulation, etc.)

• What you expect the input and output to look like: if it is text, then a quick sample of what it will look like. If it is graphical, a description or sketch of it.

It’s okay if you don’t have everything fully designed; expect the project to take shape as you go. But note that the more work you do on your design, the less time you’ll have to spend writing the code (because you’ll implement more of it correctly the first time).

Suggestion: Use AI!.

• Type in your project description as a prompt to ChatGPT, Gemini, Claude, or another AI, and ask it what a simple first-year-student Python code might look like. Use follow-up conversation with the AI to refine the problem and approach. You can also ask it to explain some aspects of the code.
• Use what you wrote as the basis for your design document; don’t copy/paste the AI output.
• Decide how you want to use the AI result. Some valid approaches:
  • Don’t use the AI-generated code any further.
  • OR: Take notes from the AI-generated code – then delete the AI code and refer to those notes as you write your own code from scratch.
  • OR: Use the AI to help write testcases that your own code should pass.
  • OR (in some limited cases): Use the AI-generated code as a library or module in your project. (Probably it’s better to use an existing library/package, though.)

Last year I allowed students to use AI-generated code under certain conditions. But students often had trouble explaining the code that the AI generated, showing that they didn’t really understand what the code was doing. So this year the policy is simpler: if you want to use some AI-generated code (or code from blog posts, StackOverflow, etc.) in your code, send it to the instructor for approval before you use it.

Regardless of how you use the AI (or other references like blog posts, tutorials, or sample code), you should be able to explain every part of your code during the walkthrough. If you can’t, you should probably rewrite it.

General Notes ¶

What kinds of projects can you work on? Almost anything that you can imagine to be “scientific computing”, “modeling”, or education. For example:

• A simulation of some physical or biological system (e.g., a solar system, a ball bouncing in some environment, a predator/prey system, etc.)
• A data analysis project
• A game that teaches or illustrates some concept
• An interactive explanation of some concept (e.g., from math, physics, chemistry, biology, psychology, economics, etc.)

I encourage you to investigate and (hopefully) use existing Python packages. Interesting ones include:

• Plotting and Visualizing: matplotlib, plotly
• Simulation: vpython, pymunk, …
• Calculating: numpy, scipy, pandas, sklearn
• Astronomy: astropy, skyfield
• Chemistry: rdkit, openbabel
• Bioinformatics: biopython
• Others: sympy, spacy, transformers, way way more

Ideas ¶

• Take something we did together (class, lab, etc.) and extend it in some way. (Some assignments have “optional extensions”; do a few of those?)

• Run a psych experiment, like a Just-Noticeable Differences test or a Stroop test.

• Make a simulation of a physical system, like a flush toilet, a garage door, or our solar system.

• Teach a concept from an area of interest to you. e.g., find a YouTube video that explains something (like one of the excellent 3blue1brown videos or others), make an interactive version of that explanation.

• Make some generative art!! For some inspiration, see:

  • Jonathan Chaffer’s CS Seminar slides
  • #genuary
  • #RecreationThursday (original pieces)
  • Generative Art at ObservableHQ
  • Truchet images | Ned Batchelder
  • generativepy tutorial
  • the “Animation Demo” that shows up when you run streamlit hello (see it running on the web)

• Simulate how political (or other) polarization develops. Example blog post.

• Build a traffic simulation. e.g., can you time traffic lights to maximize flow?

• Use SymPy to check someone’s algebra and show them what step they made a mistake on.

• Get some inspiration from Peter Norvig’s pytudes “Python etudes”

• Simulate a ball being shot out of a cannon and bouncing on the ground. What if the wind picks up? Or gravity increases?

• Simulate a predator/prey situation: wolves eat mice, so the mouse population goes down, so the wolf population goes down, so the mouse population goes up, so the wolf population goes up, and so on. Can it be extended to involve 3 species? I want to see graphs! And, it would be nice if it could be based on some actual data (found on the web, or elsewhere).

• Iterate over a collection of atoms/molecules and compute whether or not they can (theoretically) combine. If they can combine to form a new molecule, can you determine its official name. Can you use pymol to visualize the molecule?

• Newton’s method illustration

• Do something with music: transpose a chord chart, generate random melodies, etc.

  • Here’s an example of music generated from the Collatz sequence (background info here)

• Make a game. But make it a game with a point. e.g., if you’re going to do Hangman, teach us something about letter frequency and what that means for making effective guesses. If you do Minesweeper, teach us something about posterior probabilities and how to reason about uncertainty. If you do Tic-Tac-Toe, show us how to implement a minimax algorithm.

  • Sample code for a Tic-Tac-Toc game, guessing game, and colliding-particles games are available on request.
  • In prior years, students have built games including Evil Hangman, Connect Four (based on the tic-tac-toe code), Battleship (using turtle graphics), Minesweeper, etc.
  • See turtle events for some examples of how to use mouse and keyboard events in turtle graphics.

• How about a practical game? e.g., talk to me about an idea for a budget game, where you cooperate with a friend to allocate money to different parts of your household / personal budget.

• Work with some text data using spacy or transformers.

• Conway’s Game of Life or some other cellular automata (many examples are shown in the thick book “A New Kind of Science”; there is a copy in the math-stats reading room.)

• Solve a few interesting problems from projecteuler.net.

Milestone 2: Project Walkthrough ¶

You will meet with me to discuss your project. You should have at least 50% of your code complete at this point. You should be able to show me what you have working, and I will give you feedback on what you have done and what you need to do to finish.

You should be prepared to discuss the following:

• What you have working so far (and how it works)
• What you still need to do
• Any problems you are having
• Any changes you have made to your design document

I will:

• Help you strategize how to finish your project
• Give an estimate of what grade you would get if you submitted your project as is (this is not a guarantee, but it should give you an idea of where you stand)
• Discuss ideas for what you could do to improve your project

Milestone 3: Project Showcase ¶

During our final exam time, you will demo your project to the class.

We will divide up by rows. Each person will demo their project to others in the row. Each row will then nominate one project to show to the whole class.

Most people will only need to bring their running code. If you are doing a simulation project or something else that requires more explanation or summary, though, you might find it helpful to make slides.

Although this event will feel pretty informal, you should still:

• Be there! Attending and presenting a project counts for 5% of your project grade.
• Be prepared to show your code running. (It doesn’t have to be perfect.)
• Be prepared to answer questions about your project.

For a team project, each team member should be present and contribute.

Milestone 4: Final Code and README ¶

Submit a ZIP file on Moodle that includes:

• Your code

• If any data is needed to run the code, please either include the data in the ZIP file or provide specific instructions for how to obtain it (e.g., go to a certain URL).

• A screenshot or very brief video of your project in action.

• A plain-text README.txt file (which you can create using Thonny or another app like Notepad or TextEdit) that looks like:

  Title: (a title for your project)
  Author: (your name)
  Objective: 1-2 sentence description of your project's goal
  
  How to demo:
  *Specific instructions for what to do to run through a basic demo
  of the main functionality of your project.* You don't need to show
  off all features here.
  
  Highlights:
  *List a few parts of the program that you're proud of.*
  This could be something tricky you got working or how you organized
  your code.
  
  Process:
  *A one-paragraph summary on your process for creating the code.
  Include at least one specific difficulty that you encountered
  and how your overcame it.*
  
  Testing:
  *What steps could someone do to check that your code works correctly?*
  For example, if your program used to have a bug but now you fixed it,
  describe how you can test that it's fixed.
  (If you use assert statements, running the code may suffice.)
  
  Sharing: Would you be okay with sharing your project, and if so, how?
  - Ideally we'd make a public gallery with all projects, screenshots, and code, but you could choose to:
    - Go anonymous (answer "anon" or "names")
    - Don't share code? (answer "code" or "screenshots" or "just title")
    - Restrict to just future students (answer "public" or "students").
  

Grading ¶

I will grade your project submission as follows:

• 50%: code is complete and correct

• 10%: the README describes a simple and clear way to test that the code is complete and correct

  • This is especially important the more complex the code is.
  • Ideally you’d use assert statements or other kinds of automated testing, but a testing script (“click this, that should appear, and it should be less than the other thing”):

• 10%: code is well structured: easy to change correctly

  • major functionality separated into manageable chunks using functions, classes, modules, etc.
  • clear separation between “frontend” stuff (that uses input() / print / GUI widgets) and “backend” stuff (that doesn’t).
  • minimal duplication
  • constants used for any “magic” numbers

• 10%: documentation

  • variables, functions, function parameters, and classes have clear and consistent names
  • anything non-obvious has an accurate and sufficient comment and/or docstring

• 5%: submission ZIP file includes a README with all elements given above

• 5%: submission ZIP file includes a screenshot or brief demo video

• 10%: complexity/significance of the project

Note that it is better to choose a final project that is not overly complex and get it right than it is to choose a project that is too complex and not finish it. I recommend that you find a project that you can implement in stages, so that at multiple points you can have a “finished” project, and then decide if you want to or have time to proceed to the next stage. If you choose this route, it would be best to document these stages in your design document.

Testing ¶

You can use assert to test your functions. For example:

def double(x):
    return x * 2

def is_close(x, y):
    return abs(x - y) < .001

assert is_close(double(2), 4)
assert is_close(double(3), 6)

Reuse vs Plagiarism ¶

It can be very helpful to find an example we did in class (lab, homework, etc.) that is similar to what you want to do and adapt it. This is highly encouraged. Just note that you did so in your code documentation.

If you intend to use code from other people outside of the class, talk to us first and remember that we’ll grade you on the code you write, not on what other people write. If you do make use of existing code and libraries, be sure to clearly indicate who wrote what parts of the code; using code without proper attribution is a form of plagiarism.

Feel free to discuss ideas with us or with your classmates, but don’t copy code (i.e. plagiarize). Here are examples of what plagiarism looks like:

• You find a program online and copy the entire contents of the file into your submission without attribution.
• You find code online, and change the variable names.
• Your roommate writes some code, which you add to your program. You add documentation that shows you understand the code, but never indicate the source of the code.
• Your older sibling sends you a function that will help your program. You add it to your submission without attribution.

Consider these rules of thumb:

• If you found it efficient to use copy/paste to create some portion of your application, you must supply documentation that indicates the original source of the code.
• If the moment you figure out how to do something occurs while you are looking at a website, you should document that website.

Note that these rules of thumb apply to the code supplied in this course’s materials as well.

Resources ¶

• Project Code Samples
• awesome-python or similar

Streamlit stuff ¶

• In lab we did image manipulation by hand, but for your project you can use functionality that’s built into the Pillow library.
• Streamlit Components - Community Tracker

Games in Streamlit ¶

State management in streamlit is a bit tricky because the file re-runs from the top every time. I usually solve this by having a game-state object that gets stored in session state; see this grid demo. Here are some more examples and documentation:

• You’ll need to understand something about Session State (their blog post).
• tic-tac-toe demo
• some more examples (see my fork)

Other Game Engines ¶

There’s lots of game engines for Python. Some of them might be hard to learn, but might be worthwhile depending on the complexity of what you’re trying to do.

Datasets ¶

• Kaggle Datasets
• data.gov
• Our World in Data
• CORGIS Datasets Project (“The Collection of Really Great, Interesting, Situated Datasets”): https://think.cs.vt.edu/corgis/
• NOAA climate data
• US Geological survey live feeds, including recent earthquakes

Acknowledgments ¶

Like most CS 106 material, these instructions were based on material written for a prior offering of this class by Dr. Victor Norman.