# HW1: Adaptive Filtering

Due: <span style="color:red;">Tue, 2024/3/19 23:59</span>

[toc]

# Problem Description

In this assignment, you will create a C++ program that uses adaptive filtering to denoise images, preserving visual details and removing unwanted noise. **The sequential version of the program is provided**. Your task is to optimize this program by implementing multithreading, using either pthread or OpenMP. You may use std::thread as a wrapper for pthread.


# Running the Sequential Code

#### 1. Copying the Example Sequential Code:
We provide an example sequential code (hw1.cpp) along with other necessary files. Students need to copy the entire folder containing the code to their root directory using the following command:

~~~
cp -r /work/samuel21119/IPC24/hw1 ~/hw1
~~~

#### 2. Compiling the Code:

Note: Before you run the following command, please first run:

~~~
module load compiler/gcc/11.2.0
~~~

Your code will be compiled with the following command:

~~~
g++ -std=c++11 -O3 -lpng -lpthread -fopenmp hw1.cpp -o hw1
~~~

We will use `make` to build your code. The default `Makefile` for this homework is provided in the folder you have just copied. **If you wish to change the compilation flags, please include `Makefile` in your submission.**

To build your code by `make`, make sure that both the Makefile and your hw1.cpp are in the working directory. Running the `make` command line will build `hw1`
for you. To remove the built files, please execute the `make clean` command.

#### 3. Executing the Program:
After compilation, execute the program using the following command:

~~~
srun -A ACD113026 ./hw1 path/to/input.png path/to/output.png
~~~

Note:
* Replace **path/to/input.png** with the path to the noisy input image.
* Replace **path/to/output.png** with the filename where you want to save the denoised output image.

Example:
~~~
srun -A ACD113026 ./hw1 cases/input_1.png output.png
~~~

#### 4. Evaluation Settings for Code Submission:

Your code will be evaluated with a command equalviant to:

~~~
srun -A ACD113026 -n1 -c${threads} ./hw1 ${input_path} ${output_path}
~~~

where:

* `${threads}` is the number of threads
* `${input_path}` is the path to the input file
* `${output_path}` is the path to the output file

The time limit for each input test case is 8 seconds. `${threads}=8` for all test cases.

## Input Format
- The input to the program is an RGB PNG image file containing a noisy image.
- The filename is given from the command line in `argv[1]`.
- Example Input: 

## Output Format
- The output of the program is an RGB PNG image file containing the denoised image.
- The filename is given from the command line in `argv[2]`
- Example Output: 

# Report

Answer the following questions, in either English or Traditional Chinese.

1. Describe your implementation. How did you distribute your workload across different threads?

2. What are the difficulties encountered in this homework? How did you solve them?

3. What are the strengths and weaknesses of pthread and OpenMP?

4. Performance Analysis
- Draw a plot showing the relationship between the number of cores used and the program execution time.
- Analyze the plot: Is the relationship linear? If not, provide reasons for the observed behavior.

5. (Optional) Any suggestions or feedback for the homework are welcome.

# Submission

Please upload the following files to EEClass:

* `hw1.cpp` -- the source code of your implementation.
* `report.pdf` -- your report.
* `Makefile` -- optional. Submit this file if you want to change the build command.

Please follow the naming listed above carefully. Failing to adhere to the names
above will result to points deduction. Here are a few bad examples: `hw1.c`,
`HW1.cc`, `report.docx`, `report.pages`.

# Grading

1. (40%) Correctness. Propotional to the number of test cases solved.
2. (30%) Performance. Based on the total time you solve all the test cases (including hidden test cases). For a failed test case, (TBD) seconds is added to your total time.
3. (30%) Report.

# Appendix

Please note that in this spec, the sample test cases and programs might contain bugs.
If you spotted a potential one and are not quite sure about it, please raise a question on EEClass.

## Sample Testcases

The sample test cases are located at `~/hw1/cases`.

## Automatic Judge

The `hw1-judge` command can be used to automatically judge your code against all sample test cases. It also submits your execution time to the scoreboard so that you can compare your performance with the others in the class.

The scoreboard is [here](http://140.114.89.61/hw1/).

**Before using the judge system, you need to set up the environment by running the following command:**

~~~
bash <(curl -s http://140.114.89.61/setup.sh)
~~~

After that, please reopen your terminal or run the following:

~~~
source ~/.bashrc
~~~

**Note that you only need to set up the environment once.** After configuring the environment for the auto judge system, there's no need to repeat the setup process.

To use it, run `hw1-judge` in the directory that contains your code `hw1.cpp`.
It will automatically search for `Makefile` and use it to compile your code,
or fallback to the TA provided `Makefile` otherwise.
If code compiliation is successful, it will then run all the sample test cases, and show you the results as well as update the scoreboard.

- Example results:

> Note: `hw1-judge` and the scoreboard has nothing to do with grading.
> Only the code submitted to eeclass is considered for grading purposes.

### Judge Verdict Table

| Verdict | Explaination |
|--|--|
| internal error | there is a bug in the judge |
| time limit exceed+ | execution time > time limit + 10 seconds |
| time limit exceed | execution time > time limit |
| runtime error | your program didn't return 0 or is terminated by a signal |
| no output | your program did not produce an output file |
| wrong answer | your output is incorrect |
| accepted | you passed the test case |

###### tags: `spec`