Core functions and exceptions¶

Functions¶

complexplorer.phase ¶

phase(z: complex | ndarray) -> float | np.ndarray

Calculate phase (argument) of complex values in [0, 2π).

The phase is the angle of the complex number in polar form, mapped to the interval [0, 2π) for consistent coloring.

Parameters:

Name	Type	Description	Default
`z`	`complex or ndarray`	Complex value(s).	required

Returns:

Type	Description
`float or ndarray`	Phase values in [0, 2π).

Examples:

>>> phase(1+0j)
0.0
>>> phase(1j)
1.5707963267948966  # π/2
>>> phase(-1+0j)
3.141592653589793   # π

complexplorer.sawtooth ¶

sawtooth(x: float | ndarray, period: float = 1.0) -> float | np.ndarray

Generate sawtooth wave with values in [0, 1).

Creates a periodic sawtooth function that maps input values to the interval [0, 1). Used for creating periodic patterns in enhanced phase portraits.

Parameters:

Name	Type	Description	Default
`x`	`float or ndarray`	Input values.	required
`period`	`float`	Period of the sawtooth wave.	`1.0`

Returns:

Type	Description
`float or ndarray`	Sawtooth values in [0, 1).

Examples:

>>> sawtooth(0.5)
0.5
>>> sawtooth(1.5)
0.5
>>> sawtooth(2.3, period=2.0)
0.15

complexplorer.stereographic_projection ¶

stereographic_projection(z: complex | ndarray, project_from_north: bool = False) -> np.ndarray

Map complex plane to Riemann sphere via stereographic projection.

The stereographic projection maps the complex plane to a sphere with the point at infinity mapped to one of the poles.

Parameters:

Name	Type	Description	Default
`z`	`complex or ndarray`	Complex value(s) to project.	required
`project_from_north`	`bool`	If True, project from north pole (infinity at north). If False, project from south pole (infinity at south). Default is False for consistent zero/pole visualization.	`False`

Returns:

Type	Description
`ndarray`	Array of shape (..., 3) with (x, y, z) coordinates on sphere.

Notes

The formulas for projection from south pole are: - x = 2Re(z) / (1 + |z|²) - y = 2Im(z) / (1 + |z|²) - z = (|z|² - 1) / (1 + |z|²)

Examples:

>>> stereographic_projection(0+0j)
array([ 0.,  0., -1.])  # South pole
>>> stereographic_projection(1+0j)
array([ 1.,  0.,  0.])  # On equator

complexplorer.inverse_stereographic ¶

inverse_stereographic(x: float | ndarray, y: float | ndarray, z: float | ndarray, project_from_north: bool = False) -> complex | np.ndarray

Inverse stereographic projection from sphere to complex plane.

Maps points on the Riemann sphere back to the complex plane.

Parameters:

Name	Type	Description	Default
`x`	`float or ndarray`	Coordinates on the unit sphere.	required
`y`	`float or ndarray`	Coordinates on the unit sphere.	required
`z`	`float or ndarray`	Coordinates on the unit sphere.	required
`project_from_north`	`bool`	Must match the projection direction used.	`False`

Returns:

Type	Description
`complex or ndarray`	Complex values.

Notes

For projection from south pole: - Re(w) = x / (1 + z) - Im(w) = y / (1 + z)

Points at the pole (z = -1 for south, z = 1 for north) map to infinity.

Exceptions¶

Every error the library raises derives from ComplexplorerError, so one except clause catches all of them.

complexplorer.ComplexplorerError ¶

Bases: Exception

Base class for all complexplorer-domain errors.

complexplorer.ValidationError ¶

Bases: ComplexplorerError, ValueError

Invalid argument, state, or input data.

Also subclasses :class:ValueError, so pre-3.0 except ValueError handlers continue to catch it.

complexplorer.ColormapError ¶

Bases: ValidationError

Raised for invalid colormap configuration.

A ValidationError (and therefore a ComplexplorerError and a ValueError), so handlers written against either contract keep working. Restored in 3.0 for parity with 2.0.0, which raised it for invalid colormap parameters.