Complexplorer

Transform complex mathematics into tangible art. Complexplorer brings complex function visualization into the physical world through stunning Riemann relief maps and 3D-printable mathematical ornaments.

🆕 Version 2.0 Released! Major improvements include 8 new perceptually-optimized colormaps, comprehensive documentation (5,571 lines), enhanced phase portraits with auto-scaling, and cleaner API. See the CHANGELOG and Documentation for details.

<p align="center"> <img src="examples/gallery/Riemann_relief_map_20250726.png" width="50%"> <br> <em>From mathematical function to physical sculpture: f(z) = z / (z**10 - 1)</em> </p>

🌟 What Makes Complexplorer Unique

Unlike other domain coloring libraries, Complexplorer offers:

• 🎨 Riemann Relief Maps: First library to offer modulus-scaled Riemann sphere visualizations that reveal the true topology of complex functions
• 🖨️ Direct STL Export: Transform any complex function into a 3D-printable mathematical ornament
• 🚀 PyVista Integration: 15-30x faster 3D rendering with cinema-quality output
• 🔧 Advanced Domain Composition: Create complex domains through set operations (union, intersection, difference)
• 📊 Flexible Modulus Mapping: 10+ scaling modes to highlight different function features

📦 Installation

Requirements: Python 3.11 or higher

pip install complexplorer

# Optional: For interactive matplotlib plots in CLI scripts
pip install "complexplorer[qt]"

# Optional: For high-performance 3D visualizations
pip install "complexplorer[pyvista]"

# Optional: Install everything
pip install "complexplorer[all]"

🚀 Quick Start - From Math to Matter

import complexplorer as cp

# Define your complex function
f = lambda z: (z**2 - 1) / (z**2 + 1)

# Visualize as an interactive Riemann relief map
cp.riemann_pv(f, modulus_mode='arctan', resolution=800)

# Export as a 3D-printable mathematical ornament
from complexplorer.export.stl import OrnamentGenerator

ornament = OrnamentGenerator(f, resolution=200)
ornament.generate_and_save('my_mathematical_ornament.stl', size_mm=80)

The modulus scaling creates a topographic "relief" effect - poles become mountains, zeros become valleys, and the complex phase creates colorful contours. When 3D printed, these become beautiful mathematical ornaments that capture the essence of complex functions in physical form.

Create traditional domain coloring visualizations too:

# Classic phase portrait with v2.0 API
domain = cp.Rectangle(4, 4)
cp.plot(domain, f, cmap=cp.Phase(phase_sectors=12, auto_scale_r=True))

💫 The Magic of Complex Numbers

We cannot directly see the minute details of a Dedekind cut, nor is it clear that arbitrarily great or arbitrarily tiny times or lengths actually exist in nature. One could say that the so-called 'real numbers' are as much a product of mathematicians' imaginations as are the complex numbers. Yet we shall find that complex numbers, as much as reals, and perhaps even more, find a unity with nature that is truly remarkable. It is as though Nature herself is as impressed by the scope and consistency of the complex-number system as we are ourselves, and has entrusted to these numbers the precise operations of her world at its minutest scales. ...

Moreover, to refer just to the scope and to the consistency of complex numbers does not do justice to this system. There is something more which, in my view, can only be referred to as 'magic'.

Road to Reality, Chapter 4 - Magical Complex Numbers, Sir Roger Penrose

🎨 New in v2.0: Advanced Colormap Families

Complexplorer v2.0 introduces 8 new perceptually-optimized colormap families that go beyond traditional phase portraits, offering superior print quality, accessibility, and artistic control.

Perceptually Uniform Colormaps

PerceptualPastel - Elegant OkLCh-based pastels with uniform perceived brightness

# Print-friendly, non-fluorescent colors
cp.plot(domain, f, cmap=cp.PerceptualPastel(L_center=0.55, C=0.1))

Isoluminant - Constant brightness with phase-only hue variation

# Perfect for identifying phase structure without brightness distractions  
cp.plot(domain, f, cmap=cp.Isoluminant(L=0.6, C=0.15))

CubehelixPhase - Scientific coloring with optimal grayscale conversion

# CMYK-safe, perfect for academic publications
cp.plot(domain, f, cmap=cp.CubehelixPhase(start=0.5, rotations=1.5))

Artistic & Thematic Colormaps

AnalogousWedge - Compressed hue ranges for sophisticated aesthetics

# Ocean theme (teal to navy)
cp.plot(domain, f, cmap=cp.AnalogousWedge(H_center=0.55, H_wedge=0.2))

DivergingWarmCool - Cartographic style emphasizing real/imaginary axes

# Warm for positive phase, cool for negative
cp.plot(domain, f, cmap=cp.DivergingWarmCool(warm_hue=0.08, cool_hue=0.61))

InkPaper - Nearly monochrome with subtle phase tints

# Elegant etching aesthetic for presentations
cp.plot(domain, f, cmap=cp.InkPaper(phase_strength=0.05))

EarthTopographic - Terrain-inspired with natural hillshade effects

# Zeros as valleys, poles as peaks
cp.plot(domain, f, cmap=cp.EarthTopographic(water_hue=0.55, land_hue=0.08))

FourQuadrant - Bauhaus-inspired geometric palette

# Clean, reduced palette for modern aesthetics
cp.plot(domain, f, cmap=cp.FourQuadrant(C=0.25, L_base=0.5))

All new colormaps support enhanced phase portraits with automatic scaling:

cmap = cp.PerceptualPastel(phase_sectors=6, auto_scale_r=True)  # Square cells
cp.plot(domain, f, cmap=cmap)

See our Colormap Guide for detailed comparisons and use cases.

🎨 Gallery

Explore the full range of visualizations in our Gallery, featuring:

• Phase portraits with various enhancements
• Chessboard and polar patterns
• 3D analytic landscapes
• Riemann relief maps and mathematical ornaments

<p align="center"> <a href="docs/gallery/README.md"> <img src="examples/gallery/Polar_chessboard_log_modulus_spacing_2d.png" width="30%"> <img src="examples/gallery/Phase_portrait_phase_enhanced_3d.png" width="30%"> <img src="examples/gallery/riemann_chart_2d.png" width="30%"> </a> </p>

📚 Documentation

📖 Full Documentation - Comprehensive guide with 5,571 lines of documentation

Quick Links

• Installation Guide - Get up and running
• Quickstart Tutorial - Your first visualization in 5 minutes
• User Guide - Domains, colormaps, plotting, Riemann sphere
• Gallery - Visual showcase with 50+ code examples
• API Reference - Complete API documentation
• Contributing Guide - How to contribute

Examples

• Tutorial Notebooks - 8 comprehensive tutorials (~2.5 hours)
• Application Examples - 4 real-world applications (~1.5 hours)
• Interactive Demo - Run python examples/interactive_showcase.py
• Full Examples Guide - Complete learning path

🛠️ Advanced Example

# Create an enhanced phase portrait with auto-scaling for square cells
domain = cp.Annulus(0.5, 2, center=1j)  # Annular domain
cmap = cp.Phase(phase_sectors=6, auto_scale_r=True, v_base=0.4)  # Auto-scaled enhanced phase

# 2D visualization with domain and codomain side-by-side
cp.pair_plot(domain, f, cmap=cmap, figsize=(10, 5))

# 3D analytic landscape
cp.plot_landscape(domain, f, cmap=cmap, z_scale=0.3)

# 3D landscape with modulus scaling for better visualization
cp.plot_landscape(domain, f, cmap=cmap, modulus_mode='arctan')

# Riemann sphere projection
cp.riemann(f, resolution=800, cmap=cmap)

🚀 High-Performance Riemann Relief Maps with PyVista

Experience your complex functions in stunning detail with PyVista-powered visualizations that are 15-30x faster than traditional approaches:

# Create an interactive Riemann relief map
cp.riemann_pv(f, modulus_mode='arctan', resolution=800, notebook=False)

# High-performance 3D landscape
cp.plot_landscape_pv(domain, f, cmap=cmap, notebook=False)

# Side-by-side domain and codomain relief maps
cp.pair_plot_landscape_pv(domain, f, cmap=cmap, window_size=(1600, 800))

⚠️ Pro Tip: For cinema-quality Riemann relief maps, use PyVista via command-line scripts rather than Jupyter notebooks. The CLI experience offers superior antialiasing and interactivity. Try python examples/interactive_showcase.py for the ultimate visualization experience!

📊 Modulus Scaling: The Secret to Beautiful Relief Maps

Control how the magnitude (modulus) of complex values creates the topography of your mathematical landscapes:

# Different scaling modes for various visualization needs
cp.plot_landscape(domain, f, modulus_mode='constant')     # Phase