Project #3: Your Choice!

Due: Thursday, May 23rd at 11:59pm. No extensions can be used for Project #3

Getting started

For each assignment, a Git repository will be created for you on GitHub. However, before that repository can be created for you, you need to have a GitHub account. If you do not yet have one, you can get an account here: https://github.com/join.

To actually get your private repository, you will need this invitation URL:

  • Project #3 invitation (Please check the Post “Project #3 is ready” Ed)

When you click on an invitation URL, you will have to complete the following steps:

  1. You will need to select your CNetID from a list. This will allow us to know what student is associated with each GitHub account. This step is only done for the very first invitation you accept.

Note

If you are on the waiting list for this course you will not have a repository made for you until you are admitted into the course. I will post the starter code on Ed so you can work on the assignment until you are admitted into the course.

  1. You must click “Accept this assignment” or your repository will not actually be created.

  2. After accepting the assignment, Github will take a few minutes to create your repository. You should receive an email from Github when your repository is ready. Normally, it’s ready within seconds and you can just refresh the page.

  3. You now need to clone your repository (i.e., download it to your machine).

    • Make sure you’ve set up SSH access on your GitHub account.

    • For each repository, you will need to get the SSH URL of the repository. To get this URL, log into GitHub and navigate to your project repository (take into account that you will have a different repository per project). Then, click on the green “Code” button, and make sure the “SSH” tab is selected. Your repository URL should look something like this: git@github.com:mpcs52060-spr24/proj3-GITHUB-USERNAME.git.

    • If you do not know how to use git clone to clone your repository then follow this guide that Github provides: Cloning a Repository

If you run into any issues, or need us to make any manual adjustments to your registration, please let us know via Ed Discussion.

Assignment

The final project gives you the opportunity to show me what you learned in this course and to build your own parallel system. In particular, you should think about implementing a parallel system in the domain you are most comfortable in (data science, machine learning, computer graphics, etc.). The system should solve a problem that can benefit from some form of parallelization. Similar to how the performance of an image processing system benefits from parallel data decomposition of an image. If you are having trouble coming up with a problem for your system to solve then consider the following:

Requirements

You are free to implement any parallel algorithm you like. However, you are required to at least have the following features in your parallel system:

  • An input/output component that allows the program to read in data or receive data in some way. The system will perform some computation(s) on this input and produce an output result.

  • Task #1: A sequential implementation of the system. Make sure to provide a usage statement.

  • Task #2: Basic Parallel Implementation using Channels: The first parallel implementation must use Go channels (i.e., chan). No other synchronization primitive can be used in this implementation. This means you are not allowed to use the ``sync`` package at all in this implementation. This also includes not being able to use atomics. However, how you spawn and synchronize between goroutines is solely up to you. Please refer back to the M5 resources and code examples in the upstream repository for further guidance.

  • Task #3: Work-Stealing Refinement: A work-stealing algorithm using a dequeue should be used such that the work can be split into smaller tasks, which are placed in a work queue such that threads will steal work from other threads when idle. You may either implement the dequeue as a linked-list (i.e., a chain of nodes similar to project #2), or as an array as shown in lecture. While the unbounded dequeue seems more difficult to implement, the dynamic memory management makes it unlikely that you will suffer from the ABA problem. If you choose to implement the dequeue as an array, you need to ensure that a bounded dequeue is sufficient for your application for any valid input to your program, and you need to solve the ABA problem (for example using the trick of hiding a stamp in some bits of the integer used as array index as shown in the class video).

  • Provide a detailed write-up and analysis of your system. For this assignment, this write-up is required to have more detail to explain your parallel system since we are not giving you a problem to solve. See the System Write-up section for more details.

  • Provide all the dataset files you used in your analysis portion of your write up. If these files are to big then you need to provide us a link so we can easily download them from an external source. It is likely that the work-stealing refinement is only beneficial if your input data is structured in a certain way, e.g. if items in the input are of vastly different sizes, or if subtasks in your algorithm have varying or unpredictable costs. Make sure that this is the case for your project, so that you can showcase the pros/cons of all implementations.

  • These points also include design points. You should think about the modularity of the system you are creating. Think about splitting your code into appropriate packages, when necessary.

  • You must provide a script or specific commands that shows/produces the results of your system. We need to be able to enter in a single command in the terminal window and it will run and produce the results of your system. Failing to provide a straight-forward way of executing your system that produces its result will result in significant deductions to your score. We prefer running a simple command line script (e.g., shell-script or python3 script). However, providing a few example cases of possible execution runs will be sufficient enough.

  • You are free to use any additional standard/third-party libraries as you wish. However, all the parallel work is required to be implemented by you.

  • There is a directory called proj3 with a single go.mod file inside your repositories. Place all your work for project 3 inside this directory.

System Write-up

In prior assignments, we provided you with the input files or data to run experiments against a your system and provide an analysis of those experiments. For this project, you will do the same with the exception that you will produce the data needed for your experiments. In all, you should do the following for the writeup:

  • Run experiments with data you generate for both the sequential and parallel versions. As with the data provided by prior assignments, the data should vary the granularity of your parallel system. For the parallel version, make sure you are running your experiments with at least producing work for N threads, where N = {2,4,6,8,12}. You can go lower/larger than those numbers based on the machine you are running your system on. You are not required to run project 3 on the Peanut cluster. You can run it on your local machine and base your N threads on the number of logical cores you have on your local machine. If you choose to run your system on your local machine then please state that in your report and the your machine specifications as well.

  • Produce speedup graph(s) for those data sets.

Please submit a report (pdf document, text file, etc.) summarizing your results from the experiments and the conclusions you draw from them. Your report should include your plot(s) as specified above and a self-contained report. That is, somebody should be able to read the report alone and understand what code you developed, what experiments you ran and how the data supports the conclusions you draw. The report must also include the following:

  • Describe your program and the problem it is trying to solve in detail.

  • A description of how you implemented your parallel solutions. You probably want to discuss things like load balancing, latency/throughput, etc.

  • Describe the challenges you faced while implementing the system. What aspects of the system might make it difficult to parallelize? In other words, what to you hope to learn by doing this assignment?

  • Did the usage of a task queue with work stealing improve performance? Why or why not?

  • Specifications of the testing machine you ran your experiments on (i.e. Core Architecture (Intel/AMD), Number of cores, operating system, memory amount, etc.)

  • What are the hotspots (i.e., places where you can parallelize the algorithm) and bottlenecks (i.e., places where there is sequential code that cannot be parallelized) in your sequential program? Were you able to parallelize the hotspots and/or remove the bottlenecks in the parallel version?

  • What limited your speedup? Is it a lack of parallelism? (dependencies) Communication or synchronization overhead? As you try and answer these questions, we strongly prefer that you provide data and measurements to support your conclusions.

  • Compare and contrast the two parallel implementations. Are there differences in their speedups?

Don’t know What to Implement?

If you are unsure what to implement then by default you can reimplement the image processing assignment using the required new features.

You cannot reimplement project 2 or other assignments.

Grading

For this project, we grade as follows:

  • 50% Completeness. Your code should implement the required features without deadlocks or race conditions.

  • 20% Performance. Does your code scale, did you avoid unnecessary data copies, did you make an effort to remove obvious performance bottlenecks.

  • 20% Writeup. Is the report detailed, reasonably well written, and contains all the parts we asked for.

  • 10% Design and Style.

Design, Style and Cleaning up

Before you submit your final solution, you should, remove

  • any Printf statements that you added for debugging purposes and

  • all in-line comments of the form: “YOUR CODE HERE” and “TODO …”

  • Think about your function decomposition. No code duplication. This homework assignment is relatively small so this shouldn’t be a major problem but could be in certain problems.

Go does not have a strict style guide. However, use your best judgment from prior programming experience about style. Did you use good variable names? Do you have any lines that are too long, etc.

As you clean up, you should periodically save your file and run your code through the tests to make sure that you have not broken it in the process.

Submission

Before submitting, make sure you’ve added, committed, and pushed all your code to GitHub. You must submit your final work through Gradescope (linked from our Canvas site) in the “Project #3” assignment page via two ways,

  1. Uploading from Github directly (recommended way): You can link your Github account to your Gradescope account and upload the correct repository based on the homework assignment. When you submit your homework, a pop window will appear. Click on “Github” and then “Connect to Github” to connect your Github account to Gradescope. Once you connect (you will only need to do this once), then you can select the repsotiory you wish to upload and the branch (which should always be “main” or “master”) for this course.

  2. Uploading via a Zip file: You can also upload a zip file of the homework directory. Please make sure you upload the entire directory and keep the initial structure the same as the starter code; otherwise, you run the risk of not passing the automated tests.

As a reminder, for this assignment, there will be no autograder on Gradescope. We will run the program the CS Peanut cluster and manually enter in the grading into Gradescope. However, you must still submit your final commit to Gradescope.