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.

From mathematical function to physical sculpture: f(z) = z / (z**10 - 1)

🌟 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

📚 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 only (flat)
cp.plot_landscape(domain, f, modulus_mode='arctan')       # Smooth bounded scaling
cp.plot_landscape(domain, f, modulus_mode='logarithmic')  # Emphasize poles/zeros
cp.plot_landscape(domain, f, modulus_mode='adaptive')     # Auto-adjust to data

# Custom scaling function for specific needs
def custom_scale(moduli):
    return np.tanh(moduli / 2)  # Custom transformation

cp.plot_landscape(domain, f, modulus_mode='custom', 
                 modulus_params={'scaling_func': custom_scale})

Available modes: none, constant, linear, arctan, logarithmic, linear_clamp, power, sigmoid, adaptive, hybrid, custom. See examples/modulus_scaling_showcase.py for comprehensive examples.

🎯 Domain Restrictions

Control numerical stability and focus visualizations on regions of interest by restricting to specific domains:

# Avoid infinity at large distances
domain = cp.Disk(radius=5, center=0)
cp.riemann_pv(f, domain=domain, modulus_mode='arctan')

# Exclude origin for functions with poles
domain = cp.Annulus(inner_radius=0.1, outer_radius=10, center=0)
ornament = cp.OrnamentGenerator(func=lambda z: 1/z, domain=domain)

Domain restrictions work with all visualization functions and are especially useful for:

• Functions with essential singularities
• Focusing on specific regions of the complex plane
• Improving numerical stability in STL generation
• Creating cleaner 3D prints by excluding problematic areas

🖨️ 3D Printing: Mathematical Ornaments

Transform your Riemann relief maps into physical mathematical ornaments! Complexplorer is the first library to offer direct STL export of complex function visualizations:

from complexplorer.export.stl import OrnamentGenerator

# Create a mathematical ornament from any complex function
ornament = OrnamentGenerator(
    func=lambda z: (z - 1) / (z**2 + z + 1),
    resolution=150,
    scaling='arctan',  # Creates beautiful topographic relief
    cmap=cp.Phase(phase_sectors=12, auto_scale_r=True)
)

# Generate print-ready STL file
ornament.generate_and_save('mathematical_ornament.stl', size_mm=80)

Features for perfect mathematical ornaments:

• Automatic mesh healing for watertight, printable models
• Multiple scaling methods to emphasize different mathematical features
• Domain restrictions to handle singularities gracefully
• Optimized for FDM printing - no supports needed
• Compatible with all colormaps for reference when painting

Your mathematical functions become conversation pieces - imagine gifting a physical representation of the Riemann zeta function or decorating with the beauty of elliptic functions!

See examples/notebooks/08_stl_export.ipynb for a complete guide to creating mathematical ornaments.

🤝 Contributing

Contributions are welcome! Please feel free to:

• Report bugs or suggest features via Issues
• Submit pull requests with improvements
• Share your visualizations and examples
• Improve documentation

📖 Citation

If you use Complexplorer in your research, please cite:

@software{complexplorer,
  author = {Igor Kuvychko},
  title = {Complexplorer: A Python library for visualization of complex functions},
  url = {https://github.com/kuvychko/complexplorer},
  year = {2024}
}

🙏 Acknowledgments

This library was inspired by Elias Wegert's beautiful book "Visual Complex Functions" and benefited greatly from his feedback and suggestions.

📝 License

• Code: MIT License — free for personal, academic, or commercial use.
• Renders & STL outputs in this repository: CC BY-NC 4.0 — free for non-commercial use only.
  Commercial licensing (e.g. for resale, inclusion in commercial courses, or product manufacturing) is available upon request.