Parallel 3D Voxelization Project

This project converts normalized triangle meshes in .off format into voxel grids and compares five implementations of the same voxelization algorithm:

• sequential
• OpenMP
• POSIX threads
• MPI
• CUDA

The benchmark workflow measures kernel runtime, verifies every backend against the sequential reference, and exports report-ready summary tables.

Repository Layout

.
├── data/                  Input meshes
├── src/
│   ├── common/            Shared parser, SAT test, voxel grid, timing, CSV helpers
│   ├── sequential/        Sequential baseline
│   ├── openmp/            OpenMP implementation
│   ├── pthreads/          Pthreads implementation
│   ├── mpi/               MPI implementation
│   └── cuda/              CUDA implementation
├── scripts/
│   ├── bench.py           Full benchmark runner
│   ├── bench.sh           Shell wrapper for bench.py
│   └── summarize.py       Aggregation and report export
├── results/               Timestamped benchmark sessions and summaries
├── report/                Report assets
└── Makefile               Top-level build

Requirements

• gcc
• make
• mpicc and mpirun for the MPI target
• CUDA toolkit with nvcc for the CUDA target
• Python 3

Notes:

• make all builds CPU targets unconditionally and builds CUDA only if nvcc is available.
• The default CUDA architecture is sm_89. Override it if needed:

make CUDA_ARCH=sm_75 all

Build

Build everything:

make all

Useful individual targets:

make sequential
make openmp
make pthreads
make mpi
make cuda
make verify
make test

Clean generated binaries, object files, benchmark sessions, and summaries:

make clean

Running Individual Implementations

All binaries are written to bin/.

Sequential:

bin/voxelize_seq -i data/airplane_0001.off -r 64 -o results/seq.voxel -c results/sequential.csv

OpenMP:

bin/voxelize_omp -i data/airplane_0001.off -r 64 -t 4 -o results/omp.voxel -c results/openmp.csv

Pthreads:

bin/voxelize_pth -i data/airplane_0001.off -r 64 -t 4 -o results/pth.voxel -c results/pthreads.csv

MPI:

mpirun -np 4 bin/voxelize_mpi -i data/airplane_0001.off -r 64 -o results/mpi.voxel -c results/mpi.csv

CUDA:

bin/voxelize_cuda -i data/airplane_0001.off -r 64 -b 128 -o results/cuda.voxel -c results/cuda.csv

Verify a backend output against the sequential output:

bin/verify results/seq.voxel results/omp.voxel

Benchmark Matrix

The benchmark runner uses:

• Meshes: 9 input meshes from data/
• Resolutions: 32, 64, 128
• Repeats: 3
• OpenMP threads: 1, 4, 8
• Pthreads threads: 1, 4, 8
• MPI processes: 1, 4, 8
• CUDA block sizes: 64, 128, 256

Each benchmark run:

• creates a fresh timestamped session under results/run_*
• writes one CSV per backend into that session
• writes voxel outputs for each run/configuration
• verifies every non-sequential output against the sequential reference

Reproducing All Results (Hybrid Workflow)

Since the project uses both CPU backends (Sequential, OpenMP, Pthreads, MPI) and a GPU backend (CUDA), follow this hybrid workflow to generate the final report data.

1. Local Run (CPU Backends)

On your local machine (Mac/Linux):

make clean
make all
# Run only CPU backends to avoid CUDA/MPI issues locally
python3 scripts/bench.py --backends sequential openmp pthreads mpi

This will create a session folder like results/run_20260428_120000/. Keep note of this folder name.

2. Google Colab Run (GPU Backend)

1. Upload CUDA_Colab.ipynb to Google Colab.
2. Set Runtime to T4 GPU.
3. Run all cells. The notebook is configured to run python3 scripts/bench.py --backends cuda.
4. The notebook will automatically prompt you to download cuda.csv once finished.

3. Merging and Summarizing

1. Locate the cuda.csv you downloaded from Colab.
2. Drag/Move cuda.csv into your local session folder (e.g., results/run_20260428_120000/).
3. Run the summarizer locally:

python3 scripts/summarize.py --fresh-only

The final report tables will be generated in results/summary/.

Summary and Report Export

Default summary to stdout plus generated artifacts:

python3 scripts/summarize.py

Summarize only the newest benchmark session and emit report-ready files:

python3 scripts/summarize.py --fresh-only --format csv --per-resolution

Summarize explicit CSVs instead of auto-selecting a session:

python3 scripts/summarize.py --input results/run_20260427_173810/*.csv

Write summary outputs somewhere else:

python3 scripts/summarize.py --fresh-only --output-dir /tmp/voxel-summary

Generated files under results/summary/ include:

• overall.csv
• best_per_backend.csv
• backend_best_configs.csv
• runtime_table.csv
• speedup_table.csv
• runtime_by_resolution.csv
• runtime_by_resolution.md
• speedup_by_resolution.csv
• speedup_by_resolution.md
• cuda_blocksize_comparison.csv
• cuda_blocksize_comparison.md
• scalability.csv
• scalability_notes.md

Some of these tables were directly pasted into the report, while others were not to keep report size small.

Current Implementation Notes

• The sequential baseline is the source of truth for correctness checks.
• All benchmark CSVs use the schema:

impl,config,mesh_file,num_triangles,grid_res,elapsed_ms

• CUDA timing records kernel time only.
• The CUDA path precomputes per-face voxel bounds on the host and uploads them to the kernel to reduce repeated per-face min/max work in device code.

Troubleshooting

• If CUDA does not build, confirm that nvcc exists and that CUDA_ARCH matches your GPU.
• If MPI fails to launch, verify that mpirun works on your machine outside restricted sandboxes.
• If you want a completely fresh benchmark dataset, run make clean before python3 scripts/bench.py.

Remote

The local git repository is configured to use:

https://github.com/simenzzz/Parallel-Project

Google Colab

To run the CUDA optimizations on Google Colab:

1. Open Google Colab.
2. Select File > Upload notebook and upload CUDA_Colab.ipynb.
3. Set runtime to GPU (Runtime > Change runtime type > T4 GPU).
4. Run the cells.
5. Download Results: The notebook will automatically trigger a download for cuda.csv.
6. Merge: Copy this cuda.csv into your latest local results/run_* folder to include GPU data in your final summary.