Complex

NOTE: For technical reasons, all interactive-widgets plots in this documentation are created using Holoviz’s Panel. Often, they will ran just fine with ipywidgets too. However, if a specific example uses the param library, then users will have to modify the params dictionary in order to make it work with ipywidgets. Refer to Interactive module for more information.

spb.ccomplex.complex.plot_complex(*args, **kwargs)[source]

Plot the absolute value of a complex function colored by its argument. By default, the aspect ratio of 2D plots is set to aspect="equal".

Depending on the provided range, this function will produce different types of plots:

Line plot over the reals.
Image plot over the complex plane if threed=False. This is also known as Domain Coloring. Use the coloring keyword argument to select a different coloring strategy and cmap to set a custom color map (default to HSV).
If threed=True, plot a 3D surface of the absolute value over the complex plane, colored by its argument. Use the coloring keyword argument to select a different coloring strategy and cmap to set a custom color map (default to HSV).

Read the Notes section to learn more about colormaps.

Typical usage examples are in the followings:

Plotting a single expression with a single range.
plot_complex(expr, range, **kwargs)
Plotting a single expression with the default range (-10, 10).
plot_complex(expr, **kwargs)
Plotting multiple expressions with a single range.
plot_complex(expr1, expr2, …, range, **kwargs)
Plotting multiple expressions with multiple ranges.
plot_complex((expr1, range1), (expr2, range2), …, **kwargs)
Plotting multiple expressions with custom labels and rendering options.
plot_complex((expr1, range1, label1, rendering_kw1), (expr2, range2, label2, rendering_kw2), …, **kwargs)

Parameters:

args

exprExpr or callable

Represent the complex function to be plotted. It can be a:

Symbolic expression.
Numerical function of one variable, supporting vectorization. In this case the following keyword arguments are not supported: params.

range3-element tuple

Denotes the range of the variables. For example:

(z, -5, 5): plot a line over the reals from point -5 to 5
(z, -5 + 2*I, 5 + 2*I): plot a line from complex point (-5 + 2*I) to (5 + 2 * I). Note the same imaginary part for the start/end point. Also note that we can specify the ranges by using standard Python complex numbers, for example (z, -5+2j, 5+2j).
(z, -5 - 3*I, 5 + 3*I): surface or contour plot of the complex function over the specified domain.

labelstr, optional

The name of the complex function to be eventually shown on the legend. If none is provided, the string representation of the function will be used.

rendering_kwdict, optional

A dictionary of keywords/values which is passed to the backend’s function to customize the appearance of lines, surfaces or images. Refer to the plotting library (backend) manual for more informations.

adaptivebool, optional

If True, creates line plots by using an adaptive algorithm. Use adaptive_goal and loss_fn to further customize the output. Image and surface plots do not use an adaptive algorithm.

Default to False, which uses a uniform sampling strategy.

adaptive_goalcallable, int, float or None

Controls the “smoothness” of the evaluation. Possible values:

None (default): it will use the following goal: lambda l: l.loss() < 0.01
number (int or float). The lower the number, the more evaluation points. This number will be used in the following goal: lambda l: l.loss() < number
callable: a function requiring one input element, the learner. It must return a float number. Refer to [2] for more information.

aspect(float, float) or str, optional

Set the aspect ratio of the plot. The value depends on the backend being used. Read that backend’s documentation to find out the possible values.

at_infinityboolean, optional

Apply the transformation \(z \rightarrow \frac{1}{z}\) in order to study the behaviour of the function around the point at infinity. It is recommended to also set show_axis=False in order to avoid confusion.

backendPlot, optional

A subclass of Plot, which will perform the rendering. Default to MatplotlibBackend.

blevelfloat, optional

Controls the black level of ehanced domain coloring plots. It must be 0 (black) <= blevel <= 1 (white). Default to 0.75.

cmapstr, iterable, optional

Specify the colormap to be used on enhanced domain coloring plots (both images and 3d plots). Default to "hsv". Can be any colormap from matplotlib or colorcet.

colorbarboolean, optional

Show/hide the colorbar. Default to True (colorbar is visible).

coloringstr or callable, optional

Choose between different domain coloring options. Default to "a". Refer to [1] for more information.

"a": standard domain coloring showing the argument of the complex function.
"b": enhanced domain coloring showing iso-modulus and iso-phase lines.
"c": enhanced domain coloring showing iso-modulus lines.
"d": enhanced domain coloring showing iso-phase lines.
"e": alternating black and white stripes corresponding to modulus.
"f": alternating black and white stripes corresponding to phase.
"g": alternating black and white stripes corresponding to real part.
"h": alternating black and white stripes corresponding to imaginary part.
"i": cartesian chessboard on the complex points space. The result will hide zeros.
"j": polar Chessboard on the complex points space. The result will show conformality.
"k": black and white magnitude of the complex function. Zeros are black, poles are white.
"l":enhanced domain coloring showing iso-modulus and iso-phase lines, blended with the magnitude: white regions indicates greater magnitudes. Can be used to distinguish poles from zeros.
"m": enhanced domain coloring showing iso-modulus lines, blended with the magnitude: white regions indicates greater magnitudes. Can be used to distinguish poles from zeros.
"n": enhanced domain coloring showing iso-phase lines, blended with the magnitude: white regions indicates greater magnitudes. Can be used to distinguish poles from zeros.
"o": enhanced domain coloring showing iso-phase lines, blended with the magnitude: white regions indicates greater magnitudes. Can be used to distinguish poles from zeros.

The user can also provide a callable, f(w), where w is an [n x m] Numpy array (provided by the plotting module) containing the results (complex numbers) of the evaluation of the complex function. The callable should return:

imgndarray [n x m x 3]
An array of RGB colors (0 <= R,G,B <= 255)
colorscalendarray [N x 3] or None
An array with N RGB colors, (0 <= R,G,B <= 255). If colorscale=None, no color bar will be shown on the plot.

labelstr or list/tuple, optional

The label to be shown in the legend or colorbar in case of a line plot. If not provided, the string representation of expr will be used. The number of labels must be equal to the number of expressions.

loss_fncallable or None

The loss function to be used by the adaptive learner. Possible values:

None (default): it will use the default_loss from the adaptive module.
callable : Refer to [2] for more information. Specifically, look at adaptive.learner.learner1D to find more loss functions.

modulesstr, optional

Specify the modules to be used for the numerical evaluation. Refer to lambdify to visualize the available options. Default to None, meaning Numpy/Scipy will be used. Note that other modules might produce different results, based on the way they deal with branch cuts.

n1, n2int, optional

Number of discretization points in the real/imaginary-directions, respectively, when adaptive=False. For line plots, default to 1000. For surface/contour plots (2D and 3D), default to 300.

nint or two-elements tuple (n1, n2), optional

If an integer is provided, set the same number of discretization points in all directions. If a tuple is provided, it overrides n1 and n2. It only works when adaptive=False.

paramsdict, optional

A dictionary mapping symbols to parameters. This keyword argument enables the interactive-widgets plot, which doesn’t support the adaptive algorithm (meaning it will use adaptive=False). Learn more by reading the documentation of the interactive sub-module.

phaseresint, optional

Default value to 20. It controls the number of iso-phase and/or iso-modulus lines in domain coloring plots.

phaseoffsetfloat, optional

Controls the phase offset of the colormap in domain coloring plots. Default to 0.

rendering_kwdict or list of dicts, optional

A dictionary of keywords/values which is passed to the backend’s function to customize the appearance of lines, surfaces or images. Refer to the plotting library (backend) manual for more informations. If a list of dictionaries is provided, the number of dictionaries must be equal to the number of series generated by the plotting function.

showboolean, optional

Default to True, in which case the plot will be shown on the screen.

show_axisboolean, optional

Turn on/off the axis of the plot. Default to True (axis are visible).

size(float, float), optional

A tuple in the form (width, height) to specify the size of the overall figure. The default value is set to None, meaning the size will be set by the backend.

threedboolean, optional

It only applies to a complex function over a complex range. If False, a 2D image plot will be shown. If True, 3D surfaces will be shown. Default to False.

titlestr, optional

Title of the plot. It is set to the latex representation of the expression, if the plot has only one expression.

use_latexboolean, optional

Turn on/off the rendering of latex labels. If the backend doesn’t support latex, it will render the string representations instead.

xlabel, ylabel, zlabelstr, optional

Labels for the x-axis, y-axis or z-axis, respectively. zlabel is only available for 3D plots.

xscale, yscale‘linear’ or ‘log’, optional

Sets the scaling of the x-axis or y-axis, respectively. Default to 'linear'.

xlim, ylim, zlim(float, float), optional

Denotes the x-axis limits, y-axis limits or z-axis limits, respectively, (min, max). zlim is only available for 3D plots.

See also

plot_riemann_sphere, plot_real_imag, plot_complex_list, plot_complex_vector

Notes

By default, a domain coloring plot will show the phase portrait: each point of the complex plane is color-coded according to its argument. The default colormap is HSV, which is characterized by 2 important problems:

It is not friendly to people affected by color deficiencies.
Because it isn’t perceptually uniform, it might be misleading: features disappear at points of low perceptual contrast, or false features appear that are in the colormap but not in the data (refer to colorcet [3] for more information).

Hence, it might be helpful to chose a perceptually uniform colormap. Domaing coloring plots are naturally suited to be represented by cyclic colormaps, but sequential colormaps can be used too. In the following example we illustrate the phase portrait of f(z) = z using different colormaps:

from sympy import symbols, pi
import colorcet
from spb import *

z = symbols("z")
cmaps = {
    "hsv": "hsv",
    "twilight": "twilight",
    "colorwheel": colorcet.colorwheel,
    "CET-C7": colorcet.CET_C7,
    "viridis": "viridis"
}
plots = []
for k, v in cmaps.items():
    plots.append(
        plot_complex(z, (z, -2-2j, 2+2j), coloring="a",
            grid=False, show=False, legend=True, cmap=v, title=k))

plotgrid(*plots, nc=2, size=(6.5, 8))