fergus-oh / fractalpy

Python package for high performance fractal image and video generation.

FractalPy

Consider the recurrence relation $z_{n+1} = z_n^2 + c$ where $c$ is a complex number. The Mandelbrot set is a fractal, defined by the set of complex numbers $c$ for which this recurrence relation, with initial value $z_0 = 0$, does not diverge. Another interesting type of set, which are related to the Mandelbrot set, are Julia sets and are defined for a specific complex number $c$. To keep things brief, we will just establish the definition of a filled-in Julia set and do so in the following way: The filled-in Julia set of a complex number $c$ is the set of initial values $z_0$ for which the previously mentioned recurrence relation does not diverge. Not every filled-in Julia set is a fractal, but for almost all complex numbers $c$, they are. This project contains an implementation to generate images and videos relating to the Mandelbrot set and Julia sets.

Installation

Before installing the FractalPy package, it is recommended to create and activate a virtual environment with python 3.10. This can be done with conda by running the following commands in a terminal

$ conda create --name fractal python==3.10

$ conda activate fractal

Now the package and it's dependencies can be installed in the virtual environment, fractal, using pip.

To install the stable release, run

$ pip install fractalpy

To install the latest version, run

$ pip install git+https://github.com/Fergus-OH/FractalPy.git

To install an editable installation, clone the repository, checkout the develop branch, and install the contents with pip. This can be done with the following commands

$ git clone --branch develop https://github.com/Fergus-OH/FractalPy.git
$ cd FractalPy
$ pip install -e .

Usage

To get started with FractalPy, type the following in a terminal to show documentation for the command line interface application

$ fractalpy --help

FractalPy can be also be used directly in a notebook or python script by importing the fractalpy package

There are two ways of using FractalPy. The package can be imported to a python script with

import fractalpy as frac

# Plot the Mandelbrot set
frac.Mandelbrot().plot()

# Plot the Julia set
frac.Julia().plot()

The package also offers a command line interface that can be immediately accessed in the terminal with

fractalpy --help

For example, we can create a gif of zooming into the mandelbrot set with the following command:

fractalpy mandelbrot zoom

If FFmpeg is installed and accessible via the $PATH environment variable, then FractalPy can also generate videos, for example

fractalpy mandelbrot zoom --extension mp4

FractalPy makes use of multiprocessing to generate multiple frames simultaneously and also performs the computationally expensive calculations in parallel with jit, making it an extremely fast.

Documentation

Documentation is available on readthedocs.io, with a pdf format available here.