DistributedFractals

DistributedFractals is a command-line application for rendering fractals (e.g., Mandelbrot and Julia sets) using CPU-based parallelism with MPI. It enables high-resolution image generation across multiple processing units, making it suitable for both local and distributed rendering setups.

---

🚀 Overview

This project explores the intersection of fractal rendering and distributed computing using the Message Passing Interface (MPI). The main goals are:

• Efficiently generate complex fractal images using CPU parallelism.
• Provide flexibility via a command-line interface for full customization.

---

Features

• High-resolution fractal rendering using MPI-based parallelism
• Implements a master/worker architecture:
  • The master process generates a queue of image blocks (tasks).
  • Workers pull tasks dynamically as they finish their current ones, ensuring better load balancing.
  • Each block contributes to a portion of the final image.
• Support for Mandelbrot and Julia sets (extensible)
• Adjustable rendering parameters via CLI
• Interactive fractal exploration with zoom support
• Multiple output modes: save to disk or stream via network

🛠️ Build Instructions

⚠️ Note: This project currently supports Linux only. It relies on POSIX features and has not been tested on Windows or macOS.

Requirements

• CMake >= 3.14
• MPI implementation (e.g., MPICH or OpenMPI)

  sudo apt install openmpi-bin libopenmpi-dev openmpi-common

• C++17-compatible compiler

Compiling

To compile the project:

mkdir build
cd build
cmake -DCMAKE_CXX_COMPILER=mpicxx -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-O3" ..
make

▶️ Running the Application

Running locally

Parallel (MPI) Execution

## To run the distributed version with 8 processes
mpirun -np 8 ./fractal_mpi

## This renders a Mandelbrot image using 4 processes and saves it to mandelbrot.png.
mpirun -np 4 ./fractal_mpi -w 1080 -h 720 -z 1 -cx -0.7 -cy 0.0 -i 64 -t 0 -s 4 -od mandelbrot.png

Sequential Version

A non-MPI version is also available:

./sequential

Running on cluster

To run the program on a cluster using MPI, follow these steps:

1. Create a hostfile: This file should contain the IP addresses or hostnames of the cluster nodes, one per line. For example:

  # hostfile
  192.168.1.1
  192.168.1.2
  192.168.1.3

2. Run the program with mpirun: Use the -hostfile option to specify your custom hostfile:

mpirun -np 8 -hostfile hostfile ./fractal_mpi

Output mode

After the image is generated, the program can output at the following modes:

• Disk: Stores the generated image in the specified output filepath
• Network: Connects to a remote server and sends the generated .png image buffer through TCP. Note that this involves a server. A simple implementation of this server is located at src/scripts/image_server.py

⚙️ Command-Line Arguments

Option(s)	Argument(s)	Description
-od, --output_disk	[opt filename]	Save output image to disk. Defaults to output.png.
-on, --output_network	[opt IP [opt port]]	Send output image over TCP. Defaults to IP 0.0.0.0, port 5001.
-w, --width	<int>	Image width in pixels.
-h, --height	<int>	Image height in pixels.
-s, --samples	<int>	Number of MSAA samples. Must be a perfect square number
-b, --block_size	<int>	Size in pixels of the MPI image task.
-z, --zoom	<float>	Zoom level of the camera.
-cx, --camera_x	<float>	Camera X position.
-cy, --camera_y	<float>	Camera Y position.
-i, --iterations	<int>	Max iterations for fractal.
-t, --type	<int>	Fractal type ID.
--color_mode	<int>	Color mode type ID.
--julia-cx	<float>	Real component of Julia set C constant.
--julia-cy	<float>	Imaginary component of Julia set C constant.
--quiet	(none)	Disables all console messages.
--help	(none)	Show this help message.

Interactive visualizer

A simple interactive visualizer is also included, built using Python and Pygame. This viewer allows users to explore the fractal image by zooming into selected regions. It accepts the same command-line arguments as the fractal renderer and passes them directly to the compiled executable. Therefore, make sure the renderer has already been built before running the visualizer.

Setup

Creating python virtual environment

cd src/scripts
python3 -m venv .venv
source .venv/bin/activate

Installing pygame

pip install pygame

Running

python3 ./interactive_visualizer.py

You can also specify the number of mpi processors with argument --np <x> and the rendering executable path --executable_path <path>.

Video renderer

This project also includes a simple video renderer script that generates a sequence of frames to create a video. It repeatedly executes the compiled binary while interpolating the camera position and zoom level across frames.

Whitepaper

For the initial version of this project, a detailed whitepaper was created that delves into the implementation intricacies, emphasizing experimentation and the parallel programming architecture behind it. You can access the whitepaper in its dedicated repository, available under the releases section.

Samples!

Video

Watch the video in YouTube!