Plotting: 3D

PyVista-backed, and the only 3D path as of 3.0. Each takes filename and interactive=False for headless rendering, and return_plotter=True to keep composing — see 3D landscapes and the Riemann sphere.

complexplorer.plot_landscape_pv

plot_landscape_pv(domain: Domain | None = None, func: Callable | None = None, z: ndarray | None = None, f: ndarray | None = None, resolution: int = 100, cmap: Colormap | None = None, interactive: bool = True, notebook: bool | None = None, camera_position: str | tuple = 'iso', show_edges: bool = False, edge_color: str = 'gray', z_scale: float = 1.0, log_z: bool = False, z_max: float | None = None, modulus_mode: str = 'none', modulus_params: dict | None = None, window_size: tuple[int, int] = (800, 600), title: str | None = None, filename: str | None = None, return_plotter: bool = False, show_orientation: bool = True, **kwargs) -> pv.Plotter | None

Plot complex function as 3D landscape using PyVista.

This function provides high-performance, interactive 3D visualization with accurate per-vertex coloring (no interpolation artifacts).

Parameters:

Name	Type	Description	Default
domain	Domain	Domain object. If None, z must be provided.	None
func	callable	Complex function. If None, f must be provided.	None
z	ndarray	2D array of complex domain values.	None
f	ndarray	2D array of complex codomain values.	None
resolution	int	Resolution (number of points along longest edge).	100
cmap	Colormap	Colormap to use. Defaults to enhanced phase portrait.	None
interactive	bool	If True, show interactive widget. If False, render static.	True
notebook	bool	If True, render inline in Jupyter. If None, auto-detect.	None
camera_position	str or tuple	Camera position: 'iso', 'xy', 'xz', 'yz', or custom.	'iso'
show_edges	bool	If True, show mesh edges.	False
edge_color	str	Color of mesh edges.	'gray'
z_scale	float	Scaling factor for height.	1.0
log_z	bool	If True, use logarithmic scaling for height.	False
z_max	float	Maximum value for height clipping.	None
modulus_mode	str	How to scale the height based on modulus. See plot_landscape for available modes.	'none'
modulus_params	dict	Parameters for modulus scaling method.	None
window_size	tuple	Window size in pixels.	(800, 600)
title	str	Title for the plot.	None
filename	str	Save plot to file. Supported formats: - Static images: .png, .jpg, .jpeg - Vector graphics: .pdf, .svg, .eps - Interactive HTML: .html (requires trame)	None
return_plotter	bool	If True, return the plotter object.	False
show_orientation	bool	If True, show orientation widget.	True
**kwargs		Reserved. Passing any keyword argument here raises ValidationError; removed 2.x names are reported with their 3.0 replacement (e.g. n_theta/n_phi → resolution, show → interactive).	{}

Returns:

Type	Description
Plotter or None	The plotter object if return_plotter=True.

Examples:

>>> # Interactive visualization
>>> domain = Rectangle(4, 4)
>>> plot_landscape_pv(domain, lambda z: z**2, resolution=150)

>>> # Save static image
>>> plot_landscape_pv(domain, lambda z: 1/z,
...                   interactive=False, filename='poles.png')

complexplorer.pair_plot_landscape_pv

pair_plot_landscape_pv(domain: Domain | None = None, func: Callable | None = None, z: ndarray | None = None, f: ndarray | None = None, resolution: int = 100, cmap: Colormap | None = None, interactive: bool = True, notebook: bool | None = None, camera_position: str | tuple = 'iso', z_scale: float = 1.0, log_z: bool = False, z_max: float | None = None, modulus_mode: str = 'none', modulus_params: dict | None = None, window_size: tuple[int, int] = (1200, 600), title: str | None = None, filename: str | None = None, return_plotter: bool = False, **kwargs) -> pv.Plotter | None

Plot domain and codomain landscapes side-by-side using PyVista.

Parameters:

Name	Type	Description	Default
domain	Domain	Domain object. If None, z must be provided.	None
func	callable	Complex function. If None, f must be provided.	None
z	ndarray	2D array of complex domain values.	None
f	ndarray	2D array of complex codomain values.	None
resolution	int	Resolution.	100
cmap	Colormap	Colormap to use.	None
interactive	bool	If True, show interactive widget.	True
notebook	bool	If True, render inline in Jupyter.	None
camera_position	str or tuple	Camera position for both views.	'iso'
z_scale	float	Scaling factor for height.	1.0
log_z	bool	Use logarithmic scaling.	False
z_max	float	Maximum height value.	None
modulus_mode	str	How to scale the height based on modulus.	'none'
modulus_params	dict	Parameters for modulus scaling method.	None
window_size	tuple	Window size in pixels.	(1200, 600)
title	str	Overall figure title (shown above the paired views; the codomain panel keeps its own Codomain f(z) label).	None
filename	str	Save plot to file.	None
return_plotter	bool	If True, return the plotter object.	False
**kwargs		Reserved. Passing any keyword argument here raises ValidationError; removed 2.x names are reported with their 3.0 replacement (e.g. n_theta/n_phi → resolution, show → interactive).	{}

Returns:

Type	Description
Plotter or None	The plotter object if return_plotter=True.

complexplorer.riemann_pv

riemann_pv(func: Callable, resolution: int = 100, cmap: Colormap | None = None, domain: Optional[Domain] = None, interactive: bool = True, notebook: bool | None = None, camera_position: str | tuple = (2.5, 2.5, 2.5), window_size: tuple[int, int] = (800, 800), title: str | None = None, filename: str | None = None, show_orientation: bool = True, show_grid: bool = False, modulus_mode: str = 'constant', modulus_params: dict | None = None, return_plotter: bool = False, **kwargs) -> Optional[pv.Plotter]

Plot complex function on the Riemann sphere using PyVista.

.. versionchanged:: 2.2 The sphere orientation is corrected to the canonical convention (z = 0 at the south pole), matching the matplotlib riemann renderer and the STL ornament. Previously this renderer was vertically mirrored relative to the rest of the library.

This function provides high-performance, interactive visualization of complex functions on the Riemann sphere with various options for incorporating magnitude information.

Parameters:

Name	Type	Description	Default
func	callable	Complex function to visualize.	required
resolution	int	Resolution (number of divisions in each direction).	100
cmap	Colormap	Colormap for coloring. Defaults to Phase(6, 0.6).	None
domain	Domain	If provided, only show sphere points mapping to this domain.	None
interactive	bool	If True, show interactive widget.	True
notebook	bool	If True, render inline in Jupyter.	None
camera_position	str or tuple	Camera position.	(2.5, 2.5, 2.5)
window_size	tuple	Window size in pixels.	(800, 800)
title	str	Title for the plot.	None
filename	str	Save plot to file.	None
show_orientation	bool	If True, show orientation axes.	True
show_grid	bool	If True, show latitude/longitude grid.	False
modulus_mode	str	How to incorporate magnitude: - 'constant': Unit sphere (phase only) - 'linear': Linear scaling - 'arctan': Smooth bounded scaling - 'logarithmic': Log scaling - 'linear_clamp': Linear with clamping - 'power': Power scaling - 'sigmoid': S-curve scaling - 'adaptive': Percentile-based - 'hybrid': Linear near zero, log for large - 'custom': User-defined function	'constant'
modulus_params	dict	Parameters for modulus scaling method.	None
return_plotter	bool	If True, return the plotter object.	False
**kwargs		Reserved. Passing any keyword argument here raises ValidationError; removed 2.x names are reported with their 3.0 replacement (e.g. n_theta/n_phi → resolution, show → interactive).	{}

Returns:

Type	Description
Plotter or None	The plotter object if return_plotter=True.

Examples:

>>> # Basic visualization
>>> riemann_pv(lambda z: (z-1)/(z+1))

>>> # With magnitude scaling
>>> riemann_pv(lambda z: z**2, modulus_mode='arctan')

>>> # Custom scaling function
>>> def custom_scale(moduli):
...     return np.tanh(moduli / 2)
>>> riemann_pv(lambda z: np.sin(z), modulus_mode='custom',
...           modulus_params={'scaling_func': custom_scale})

complexplorer.riemann_surface_pv

riemann_surface_pv(family: str = 'power', *, n: int = 2, turns: int = 3, p: Sequence[float] | None = None, r_max: float = 1.5, resolution: int = 60, cmap: Colormap | None = None, interactive: bool = True, notebook: bool | None = None, camera_position: str | tuple = (2.5, 2.5, 2.5), window_size: tuple[int, int] = (800, 800), title: str | None = None, filename: str | None = None, show_orientation: bool = True, return_plotter: bool = False, **kwargs) -> pv.Plotter | None

Render the Riemann surface of a multivalued family with PyVista.

Parameters:

Name	Type	Description	Default
family	str	"power" (z**(1/n)), "log", or "algebraic" (w**2 = P(z)).	"power"
n	int	Sheet count for the power family (sqrt=2, cbrt=3, ...).	2
turns	int	Number of 2*pi turns for the log helicoid.	3
p	sequence of numbers	Polynomial coefficients of P for the algebraic family (numpy.polyval order, highest degree first); e.g. [1, 0, -1, 0] is the elliptic curve w**2 = z**3 - z. Required when family="algebraic".	None
r_max	float	Radius in the z-plane that the surface spans. For the algebraic family choose it to enclose the interesting branch points (the roots of P).	1.5
resolution	int	Radial sample count.	60
cmap	Colormap	Colormap for the phase of the value. Defaults to Phase(phase_sectors=6, v_base=0.6).	None
interactive	bool	Show an interactive window. If False, render off-screen.	True
notebook	bool | None	Standard PyVista renderer options (see riemann_pv).	None
camera_position	bool | None	Standard PyVista renderer options (see riemann_pv).	None
window_size	bool | None	Standard PyVista renderer options (see riemann_pv).	None
title	bool | None	Standard PyVista renderer options (see riemann_pv).	None
filename	bool | None	Standard PyVista renderer options (see riemann_pv).	None
show_orientation	bool | None	Standard PyVista renderer options (see riemann_pv).	None
return_plotter	bool | None	Standard PyVista renderer options (see riemann_pv).	None
**kwargs		Reserved. Passing any keyword argument here raises ValidationError.	{}

Returns:

Type	Description
Plotter or None	The plotter if return_plotter is True, else None.