---
# System prepended metadata

title: 'HW2: Mandelbulb'
tags: [spec]

---

# HW2: Mandelbulb

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

[TOC]
## Problem Description

In this assignment, you are asked to implement a simplest Ray Marching algorithm to render the “Classic” Mandelbulb and parallelize your program with MPI and OpenMP libraries. We hope this assignment helps you to learn the following concepts:

* The differences between **Static Scheduling** and **Dynamic Scheduling**.
* The importance of **Load Balancing**.
* The importance of parallel algorithms and libraries.

<span style="color:red;">**Please note that you are not allowed to use mathematical techniques to bypass or reduce the iteration process of calculating Mandelbulb sets (i.e. do not modify the parameters in the sample code).**</span>


## Provided Materials

* A sequential version of mendelbulb rendering is provided at `/work/samuel21119/IPC24/hw2/sample/hw2.cpp`.
* The default makefile is provided at `/work/samuel21119/IPC24/hw2/sample/Makefile`.
* The public testcases is provided at `/work/samuel21119/IPC24/hw2/testcases/`.

## Environment Setup and Sequential Code

**1. Copy the folder with provided materials with the following command:**

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

**2. Load the required modules for the program:**

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

**3. Compile and execute the example code:**
~~~
cd ~/hw2/sample/
make
srun -A ACD113026 -N 2 -n 3 -c 4 --mpi=pmix ./hw2 4 -0.522 2.874 1.340 0 0 0 64 64 1.png
~~~
The output image will be saved in 1.png

![1](https://hackmd.io/_uploads/SJUekG4R6.png)


**Please remember to add the '`--mpi=pmix`' flag when using srun**


## Program Execution and I/O Specifications

The program is executed with the following command:
`./executable $num_threads $x1 $y1 $z1 $x2 $y2 $z2 $width $height $filename`

The types of the arguements and their meanings are listed in the table below:

|Argument | type | explanation |
|------- | ------------| ------- |
|$num_threads | int | Number of thread per process |
| $x1 | double | camera position x | 
| $y1 | double | camera position y |
| $z1 | double | camera position z |
| $x2 | double | camera target position x |
| $y2 | double | camera target position y | 
| $z2 | double | camera target position z |
| $width | unsigned int | width of the image |
| $height | unsigned int | height of the image |
| $filename | string | file name of the output PNG image |

**Please note that the output image should be a 32bit PNG image with RGBA channels.**

## Parameter For Mandelbulb Rendering

The table below lists the parameters, along with their default values and explanations, in the sequential version.

|Parameter | Default Value | explaination |
|------- | ------------| ------- |
| power | 8.0 | Power of the equation | 
| md_iter | 24 | The mandelbulb's maximum iteration count  |
| ray_step | 10000 | The maximum step count of ray marching |
| shadow_step | 1500 | The maximum step count of shadow casting |
| step_limiter | 0.2 | The limit length of each step when casting shadow | 
| ray_multiplier | 0.1 | A multiplier for ray marching to prevent over-shooting |
| bailout | 2.0 | The escape radius |
| eps | 0.0005 | The precision of the rendering calculation |
| FOV | 1.5 | Field of view |
| far_plane | 100 | The maximum depth of the scene |

## Library Used

The following libraries are the ones used for the sequential version. Please refer to TA’s sample code and Makefile.

1. [lodepng](https://github.com/lvandeve/lodepng) - loading/saving PNG images. [C/C++]
2. [GLM](https://github.com/g-truc/glm) - vector/matrix arithmetic. [C++]

## Output Verification

<!-- A simple script is provided for you to test the correctness of the rendered image. Once invoked, it compares the two input images and outputs the percentage of matching pixels. This script can be invoked using the following command:

`/home/ipc23/share/hw2/hw2-diff a.png b.png` -->

You can use `hw2-judge` to check the correctness of your program on all testcases and submit your result to the [scoreboard](http://elsa-judge.cs.nthu.edu.tw/hw2/?fbclid=IwAR1DY_Q9OsvpSWM2zPssBQthEdpJIHUXFn0OiYTFohB17IGnrAoYQacKCtM).
<font color=red>**Please note that your homework is graded base on the code submitted to EEClass, the statistics on the scoreboard will not be considered**</font>
**Please also remember to load the modules mentioned above before using the auto-judge.**
 
## Report 

Your report must contain the following contents, and you can add more as you like. You can write in either **English or Traditional Chinese**.

1. Name, Student ID:
    - Name: your name.
    - StudentID: your student ID.
2. Explain your implementation, especially in the following aspects:
    - How do you implement your program, what scheduling algorithm did you use: static, dynamic, guided, etc.?
    - How do you partition the task?
    - What techniques do you use to reduce execution time?
    - Other efforts you make in your program.
3. Analysis:
    - Design your own plots to show the load balance of your algorithm between threads/processes.
    - Analyze your program's scalability in the following aspects
        - number of CPU cores per process
        - number of processes per node
        - number of nodes
    - Other things worth mentioning.
4. Conclusion:
    - What have you learned from this assignment?
    - What difficulty did you encounter in this assignment?
    - Any feedback or suggestions to this assignment or spec.


## Grading
1. (50%) Correctness:
    - Additional hidden testcases will be used to test your program.
    - If the ouptut png file of your program fails to match 98% of the ground truth, you will get 0 points for that test case.
    
3. (20%) Performance. Based on the total time you solve all the test cases. Note that you are required to produce the right answer to get the performance points.

5. (30%) Report.

## Submission 

Please submit the following files to EEClass:

1. `hw2.cpp`
2. `Makefile` (optional)
3. `report.pdf`

## Reminder

1. Please submit your homework before 4/2 23:59
2. If you spot any problem in this specification or are unsure about the specification, please feel free to **raise your question on EEClass**.

###### tags: `spec`