API Reference

This section provides detailed API documentation for py-domaincolor.

High-Level Functions

These are the main entry points for most users.

plot

py_domaincolor.plot_complex.plot_complex_function(expression, x_range=(-2, 2), y_range=None, resolution=400, output_path=None, show_legend=True, dark_theme=True)[source]

Parse and plot a complex function using domain coloring.

This function: 1. Parses the expression string using complex-expr-parser 2. Renders the domain coloring plot using cplot (via our wrapper) 3. Saves and returns the output path

Parameters:

  • expression (str) – Human-friendly function string (e.g., “z^2”, “sin(z)/z”)

  • x_range (tuple) – (min, max) for real axis

  • y_range (tuple) – (min, max) for imaginary axis (defaults to match x_range)

  • resolution (int) – Grid resolution

  • output_path (str) – Where to save the image

  • show_legend (bool) – Include color wheel legend

  • dark_theme (bool) – Use dark background

Returns:

Path to saved image

Return type:

str

parse

get_callable

validate_expression

Parser Module

ComplexFunctionParser

Domain Coloring Module

Domain coloring visualization wrapper around cplot.

This module provides a thin wrapper around the cplot library for domain coloring visualization. It exposes a simplified interface that accepts expression strings and common options, delegating the actual rendering to cplot.

cplot reference:

cplot.plot(f, (x_min, x_max, n_x), (y_min, y_max, n_y), **kwargs)

Note: cplot.plot() does not accept an ‘ax’ parameter - it creates its own figure. This wrapper handles figure management appropriately.

py_domaincolor.domain_coloring.domain_color_plot(f, x_range=(-2, 2), y_range=(-2, 2), resolution=400, title=None, figsize=(10, 10), save_path=None, show=False, ax=None, abs_scaling=None, add_colorbars=False, add_axes_labels=True)[source]

Create a domain coloring plot for a complex function using cplot.

This is a convenience wrapper around cplot.plot() that provides a simpler interface with sensible defaults.

Parameters:

  • f (Callable) – Complex function f(z) - must accept numpy arrays

  • x_range (Tuple[float, float]) – (min, max) for real axis

  • y_range (Tuple[float, float]) – (min, max) for imaginary axis

  • resolution (int) – Grid resolution (number of points along each axis)

  • title (str | None) – Plot title

  • figsize (Tuple[int, int]) – Figure size

  • save_path (str | None) – Path to save image (if provided)

  • show (bool) – Whether to display the plot (default False)

  • ax (Axes | None) – Ignored for compatibility - cplot creates its own figure

  • abs_scaling (Callable | None) – Function to scale the absolute value for brightness. Common options from cplot: - lambda x: x / (1 + x) (default-like behavior) - lambda x: np.arctan(x) / (np.pi/2) (compress large values) - lambda x: np.log(x + 1) (logarithmic)

  • add_colorbars (bool) – Whether to add colorbars (default False)

  • add_axes_labels (bool) – Whether to add axis labels (default True)

Returns:

(fig, ax) tuple

Return type:

Tuple[Figure, Axes]

py_domaincolor.domain_coloring.create_colorwheel(size=200)[source]

Create a color wheel showing the phase-to-color mapping.

This is useful for legends showing how argument maps to hue.

Parameters:

size (int) – Size of the output array (size x size pixels)

Returns:

RGB array for the color wheel

Return type:

ndarray

py_domaincolor.domain_coloring.plot_function(f, xlim=(-2, 2), ylim=(-2, 2), n=400, **kwargs)[source]

Simplified interface for plotting a complex function.

Parameters:

  • f (Callable) – Complex function

  • xlim (Tuple[float, float]) – Real axis limits

  • ylim (Tuple[float, float]) – Imaginary axis limits

  • n (int) – Resolution

  • **kwargs – Additional arguments passed to domain_color_plot

Returns:

(fig, ax) tuple

Return type:

Tuple[Figure, Axes]

Core Functions

py_domaincolor.domain_coloring.domain_color_plot(f, x_range=(-2, 2), y_range=(-2, 2), resolution=400, title=None, figsize=(10, 10), save_path=None, show=False, ax=None, abs_scaling=None, add_colorbars=False, add_axes_labels=True)[source]

Create a domain coloring plot for a complex function using cplot.

This is a convenience wrapper around cplot.plot() that provides a simpler interface with sensible defaults.

Parameters:

  • f (Callable) – Complex function f(z) - must accept numpy arrays

  • x_range (Tuple[float, float]) – (min, max) for real axis

  • y_range (Tuple[float, float]) – (min, max) for imaginary axis

  • resolution (int) – Grid resolution (number of points along each axis)

  • title (str | None) – Plot title

  • figsize (Tuple[int, int]) – Figure size

  • save_path (str | None) – Path to save image (if provided)

  • show (bool) – Whether to display the plot (default False)

  • ax (Axes | None) – Ignored for compatibility - cplot creates its own figure

  • abs_scaling (Callable | None) – Function to scale the absolute value for brightness. Common options from cplot: - lambda x: x / (1 + x) (default-like behavior) - lambda x: np.arctan(x) / (np.pi/2) (compress large values) - lambda x: np.log(x + 1) (logarithmic)

  • add_colorbars (bool) – Whether to add colorbars (default False)

  • add_axes_labels (bool) – Whether to add axis labels (default True)

Returns:

(fig, ax) tuple

Return type:

Tuple[Figure, Axes]

py_domaincolor.domain_coloring.create_colorwheel(size=200)[source]

Create a color wheel showing the phase-to-color mapping.

This is useful for legends showing how argument maps to hue.

Parameters:

size (int) – Size of the output array (size x size pixels)

Returns:

RGB array for the color wheel

Return type:

ndarray

Helper Functions

Plot Complex Module

Domain coloring plotter for complex functions.

A convenience wrapper combining complex-expr-parser for expression parsing and cplot for visualization.

Usage:

plot-complex “z^2” plot-complex “sin(z)/z” –range -5 5 plot-complex “gamma(z)” –resolution 1000

Supports human-friendly input:

  • z^2, z**2 Powers

  • sin(z), cos(z), tan(z) Trig functions

  • sinh(z), cosh(z), tanh(z) Hyperbolic functions

  • exp(z), e^z Exponential

  • log(z), ln(z) Logarithm

  • sqrt(z) Square root

  • |z|, abs(z) Absolute value

  • z*, conjugate(z) Conjugate

  • re(z), im(z) Real/imaginary parts

  • gamma(z), zeta(z) Special functions

  • i, j Imaginary unit

  • e, pi Constants

py_domaincolor.plot_complex.add_colorbar_legend(ax, fig)[source]

Add a small color wheel legend showing phase mapping.

Parameters:
py_domaincolor.plot_complex.plot_complex_function(expression, x_range=(-2, 2), y_range=None, resolution=400, output_path=None, show_legend=True, dark_theme=True)[source]

Parse and plot a complex function using domain coloring.

This function: 1. Parses the expression string using complex-expr-parser 2. Renders the domain coloring plot using cplot (via our wrapper) 3. Saves and returns the output path

Parameters:

  • expression (str) – Human-friendly function string (e.g., “z^2”, “sin(z)/z”)

  • x_range (tuple) – (min, max) for real axis

  • y_range (tuple) – (min, max) for imaginary axis (defaults to match x_range)

  • resolution (int) – Grid resolution

  • output_path (str) – Where to save the image

  • show_legend (bool) – Include color wheel legend

  • dark_theme (bool) – Use dark background

Returns:

Path to saved image

Return type:

str

py_domaincolor.plot_complex.main()[source]

Main entry point for the plot-complex CLI.

Symbols

z

The complex variable symbol used in expressions:

from py_domaincolor import z
from sympy import sin

# Use z directly in SymPy expressions
expr = sin(z) / z