parallelbrot

Mandelbrot set renderer with CPU, OpenCL and CUDA backends — a Python package for generating fractal images, and an interactive real-time viewer.

Install

pip install parallelbrot
# or
uv add parallelbrot

Wheels are abi3, so one wheel per platform covers CPython 3.9 and up — the wheel is built on 3.9 and installs unchanged on 3.14.

The macOS floors come from Homebrew's libomp, which the wheels bundle for multi-threaded rendering. On older macOS, install from source or conda-forge.

Command line

parallelbrot                                  # 1920x1080 -> mandelbrot.png
parallelbrot -o seahorse.png -s 3840x2160 \
    -c -0.743644,0.131826 -z 4000 -i 1000 --colors ocean
parallelbrot --info                           # what backends are usable here
parallelbrot -I                               # interactive pan-and-zoom window

-I opens a live viewer: drag to pan, scroll to zoom on the cursor, arrows to pan, +/- for iterations, C to cycle palettes, R to reset, Q to quit. It needs matplotlib — pip install 'parallelbrot[viewer]'.

PNG writing is built in, so the CLI needs nothing beyond NumPy.

Python API

import parallelbrot as pb

image = pb.render(1920, 1080)                 # (1080, 1920, 4) float32 RGBA

Zoom in on the seahorse valley, and save it:

import parallelbrot as pb

image = pb.render(
    1920, 1080,
    center=(-0.743644, 0.131826),
    zoom=4000,
    max_iterations=1000,
    color_scheme="fire",
)
pb.save_png("seahorse.png", image)

save_png needs nothing beyond NumPy. The array is ordinary float32, so Pillow, matplotlib or imageio all work on it too if you already have them:

import matplotlib.pyplot as plt

plt.imshow(pb.render(800, 600, zoom=200, center=(-0.75, 0.1)))
plt.axis("off")
plt.show()

render()

Returns an (height, width, 4) float32 array with values in [0, 1].

Choosing a backend

import parallelbrot as pb

pb.available_backends()   # ('cpu',) — compiled in and a device is present
pb.compiled_backends()    # ('cpu', 'opencl') — compiled in, device or not
pb.device_name("opencl")  # 'NVIDIA GeForce RTX 4070' or None
pb.has_openmp()           # is the CPU backend multi-threaded?

backend="auto" picks the fastest backend that has a working device, falling back to the CPU.

Rendering releases the GIL, so calls from separate threads run in parallel:

import parallelbrot as pb
from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor() as pool:                       # renders a zoom
    frames = list(pool.map(                              # sequence in parallel
        lambda z: pb.render(640, 480, zoom=z), [2**i for i in range(12)]
    ))

Which backends do you get?

PyPI wheels are CPU-only on purpose. Linking OpenCL makes the extension require an ICD loader at import time, which would break the package on machines without a GPU driver — including for people who only wanted the CPU backend. conda can declare that loader as a dependency, so the GPU builds live there.

The CPU backend is not a toy: OpenMP parallelises across rows with dynamic scheduling, since interior points cost far more than exterior ones. A 1920×1080 frame at 1000 iterations takes 37 ms on 16 cores, against 506 ms single-threaded.

Interactive viewer

A real-time pan-and-zoom window, built separately from the Python package.

make install-deps-ubuntu     # or -fedora, -arch, -macos
make opencl && bin/mandelbrot_opencl   # any GPU — recommended
make cuda   && bin/mandelbrot_cuda     # NVIDIA only, fastest
make cpu    && bin/mandelbrot_cpu      # always works

make help lists every target; make check-opencl and make check-cuda report what your machine can do.

Viewer dependencies

GPU drivers: NVIDIA needs the proprietary driver or nvidia-opencl-dev; AMD needs rocm-opencl-runtime or mesa-opencl-icd; Intel needs intel-opencl-icd. macOS provides OpenCL itself.

Building from source

git clone https://github.com/prathamhole14/parallelbrot
cd parallelbrot

uv venv
uv pip install meson meson-python ninja    # must exist in the venv itself
uv sync                                    # editable install + dev dependencies

uv run pytest
uv run parallelbrot --info

Without uv:

python -m venv .venv && . .venv/bin/activate
pip install -U meson meson-python ninja
pip install -e . --no-build-isolation
pytest

Why the build tools go in the environment

An editable install of a Meson project keeps rebuilding itself: build.ninja records the path of the meson that configured it, and re-runs it whenever a source file changes. Installed the usual way, that path points inside the installer's temporary build environment, which is deleted as soon as the install finishes. Every later import then fails:

/home/you/.cache/uv/builds-v0/.tmpXXXX/bin/meson: not found
ImportError: rebuilding the "parallelbrot" editable package failed

pip does the same thing with /tmp/pip-build-env-*. Both are fixed the same way: put meson, meson-python and ninja in the target environment and build without isolation, so the recorded path still exists afterwards. This project sets no-build-isolation-package in [tool.uv] so uv sync does that automatically once the tools are present — which is why they are installed first above.

To repair an environment already in this state:

rm -rf build
uv sync --reinstall-package parallelbrot     # or: pip install -e . --no-build-isolation

--reinstall-package is needed because uv will otherwise relink a cached copy of a previous editable install and skip the build, leaving no build/ directory for the rebuild hook to use.

Build options are Meson features, so absent tooling degrades the build rather than failing it:

uv sync -C setup-args=-Dopencl=enabled    # fail if OpenCL is missing
uv sync -C setup-args=-Dopenmp=disabled   # single-threaded CPU backend
python -m build --wheel                   # a cp3XX-abi3 wheel

macOS needs brew install libomp for a multi-threaded CPU backend — Apple Clang ships without OpenMP. pb.has_openmp() tells you which you got.

Layout

include/parallelbrot/core.hpp   Shared View struct + backend entry points
src/core/                       Compute cores — no windowing, no Python
src/cpu|opencl|cuda/            Interactive frontends + device kernels
src/python/                     CPython extension (limited API)
src/parallelbrot/               Python package
meson.build, pyproject.toml     Wheel build
Makefile                        Interactive viewer binaries

The compute cores carry no GLFW, OpenGL or Python headers, so the same code serves the viewer, the Python package and the tests.

License

MIT — see LICENSE.