Complex plots#
AUTHORS:
Robert Bradshaw (2009): initial version
David Lowry-Duda (2022): incorporate matplotlib colormaps
- class sage.plot.complex_plot.ComplexPlot(rgb_data, x_range, y_range, options)#
Bases:
GraphicPrimitive
The GraphicsPrimitive to display complex functions in using the domain coloring method
INPUT:
rgb_data
– An array of colored points to be plotted.x_range
– A minimum and maximum x value for the plot.y_range
– A minimum and maximum y value for the plot.
- get_minmax_data()#
Return a dictionary with the bounding box data.
EXAMPLES:
sage: p = complex_plot(lambda z: z, (-1, 2), (-3, 4)) sage: sorted(p.get_minmax_data().items()) [('xmax', 2.0), ('xmin', -1.0), ('ymax', 4.0), ('ymin', -3.0)] sage: p = complex_plot(lambda z: z, (1, 2), (3, 4)) sage: sorted(p.get_minmax_data().items()) [('xmax', 2.0), ('xmin', 1.0), ('ymax', 4.0), ('ymin', 3.0)]
- sage.plot.complex_plot.add_contours_to_rgb(rgb, delta, dark_rate=0.5)#
Return an rgb array from given array of \((r, g, b)\) and \((delta)\).
Each input \((r, g, b)\) is modified by
delta
to be lighter or darker depending on the size ofdelta
. Negativedelta
values darken the color, while positivedelta
values lighten the pixel.We assume that the
delta
values come from a function likesage.plot.complex_plot.mag_to_lightness()
, which maps magnitudes to the range \([-1, +1]\).INPUT:
rgb
– a grid of length 3 tuples \((r, g, b)\), as an \(N \times M \times 3\) numpy array.delta
– a grid of values as an \(N \times M\) numpy array; these represent how much to change the lightness of each \((r, g, b)\). Values should be in \([-1, 1]\).dark_rate
– a positive number (default: \(0.5\)); affects how strongly visible the contours appear.
OUTPUT:
An \(N \times M \times 3\) floating point Numpy array
X
, whereX[i,j]
is an (r, g, b) tuple.See also
ALGORITHM:
Each pixel and lightness-delta is mapped from \((r, g, b, delta) \mapsto (h, l, s, delta)\) using the standard RGB-to-HLS formula.
Then the lightness is adjusted via \(l \mapsto l' = l + 0.5 \cdot delta\).
Finally map \((h, l', s) \mapsto (r, g, b)\) using the standard HLS-to-RGB formula.
EXAMPLES:
sage: import numpy as np sage: from sage.plot.complex_plot import add_contours_to_rgb sage: add_contours_to_rgb(np.array([[[0, 0.25, 0.5]]]), np.array([[0.75]])) # abs tol 1e-4 array([[[0.25 , 0.625, 1. ]]]) sage: add_contours_to_rgb(np.array([[[0, 0, 0]]]), np.array([[1]])) # abs tol 1e-4 array([[[0.5, 0.5, 0.5]]]) sage: add_contours_to_rgb(np.array([[[1, 1, 1]]]), np.array([[-0.5]])) # abs tol 1e-4 array([[[0.75, 0.75, 0.75]]])
Raising
dark_rate
leads to bigger adjustments:sage: add_contours_to_rgb(np.array([[[0.5, 0.5, 0.5]]]), # abs tol 1e-4 ....: np.array([[0.5]]), dark_rate=0.1) array([[[0.55, 0.55, 0.55]]]) sage: add_contours_to_rgb(np.array([[[0.5, 0.5, 0.5]]]), # abs tol 1e-4 ....: np.array([[0.5]]), dark_rate=0.5) array([[[0.75, 0.75, 0.75]]])
- sage.plot.complex_plot.add_lightness_smoothing_to_rgb(rgb, delta)#
Return an rgb array from given array of colors and lightness adjustments.
This smoothly adds lightness from black (when
delta
is \(-1\)) to white (whendelta
is \(1\)).Each input \((r, g, b)\) is modified by
delta
to be lighter or darker depending on the size ofdelta
. Whendelta
is \(-1\), the output is black. Whendelta
is \(+1\), the output is white. Colors piecewise-linearly vary from black to the initial \((r, g, b)\) to white.We assume that the
delta
values come from a function likesage.plot.complex_plot.mag_to_lightness()
, which maps magnitudes to the range \([-1, +1]\).INPUT:
rgb
– a grid of length 3 tuples \((r, g, b)\), as an \(N \times M \times 3\) numpy array.delta
– a grid of values as an \(N \times M\) numpy array; these represent how much to change the lightness of each \((r, g, b)\). Values should be in \([-1, 1]\).
OUTPUT:
An \(N \times M \times 3\) floating point Numpy array
X
, whereX[i,j]
is an (r, g, b) tuple.EXAMPLES:
We can call this on grids of values:
sage: import numpy as np sage: from sage.plot.complex_plot import add_lightness_smoothing_to_rgb sage: add_lightness_smoothing_to_rgb(np.array([[[0, 0.25, 0.5]]]), np.array([[0.75]])) # abs tol 1e-4 array([[[0.75 , 0.8125, 0.875 ]]]) sage: add_lightness_smoothing_to_rgb(np.array([[[0, 0.25, 0.5]]]), np.array([[0.75]])) # abs tol 1e-4 array([[[0.75 , 0.8125, 0.875 ]]])
- sage.plot.complex_plot.complex_plot(f, x_range, y_range, contoured=False, tiled=False, cmap=None, contour_type='logarithmic', contour_base=None, dark_rate=0.5, nphases=10, plot_points=100, interpolation='catrom', **options)#
complex_plot
takes a complex function of one variable, \(f(z)\) and plots output of the function over the specifiedx_range
andy_range
as demonstrated below. The magnitude of the output is indicated by the brightness and the argument is represented by the hue.By default, zero magnitude corresponds to black output, infinite magnitude corresponds to white output. The options
contoured
,tiled
, andcmap
affect the output.complex_plot(f, (xmin, xmax), (ymin, ymax), contoured, tiled, cmap, ...)
INPUT:
f
– a function of a single complex value \(x + iy\)(xmin, xmax)
– 2-tuple, the range ofx
values(ymin, ymax)
– 2-tuple, the range ofy
valuescmap
–None
, or the string name of a matplotlib colormap, or an instance of a matplotlib Colormap, or the special string'matplotlib'
(default:None
); IfNone
, then hues are chosen from a standard color wheel, cycling from red to yellow to blue. Ifmatplotlib
, then hues are chosen from a preset matplotlib colormap.
The following named parameter inputs can be used to add contours and adjust their distribution:
contoured
– boolean (default:False
); causes the magnitude to be indicated by logarithmically spaced ‘contours’. The magnitude along one contour is either twice or half the magnitude along adjacent contours.dark_rate
– a positive number (default: \(0.5\)); affects how quickly magnitudes affect how light/dark the image is. When there are contours, this affects how visible each contour is. Large values (near \(1.0\)) have very strong, immediate effects, while small values (near \(0.0\)) have gradual effects.tiled
– boolean (default:False
); causes the magnitude to be indicated by logarithmically spaced ‘contours’ as incontoured
, and in addition for there to be \(10\) evenly spaced phase contours.nphases
– a positive integer (default: \(10\)); whentiled=True
, this is the number of divisions the phase is divided into.contour_type
– either'logarithmic'
, or'linear'
(default:'logarithmic'
); causes added contours to be of given type whencontoured=True
.contour_base
– a positive integer; whencontour_type
is'logarithmic'
, this sets logarithmic contours at multiples ofcontour_base
apart. Whencontour_type
is'linear'
, this sets contours at distances ofcontour_base
apart. IfNone
, then a default is chosen depending oncontour_type
.
The following inputs may also be passed in as named parameters:
plot_points
– integer (default:100
); number of points to plot in each direction of the gridinterpolation
– string (default:'catrom'
); the interpolation method to use:'bilinear'
,'bicubic'
,'spline16'
,'spline36'
,'quadric'
,'gaussian'
,'sinc'
,'bessel'
,'mitchell'
,'lanczos'
,'catrom'
,'hermite'
,'hanning'
,'hamming'
,'kaiser'
Any additional parameters will be passed to
show()
, as long as they’re valid.Note
Matplotlib colormaps can be chosen or customized to cater to different types of vision. The colormaps ‘cividis’ and ‘viridis’ in matplotlib are designed to be perceptually uniform to a broader audience. The colormap ‘turbo’ is similar to the default but with more even contrast. See [NAR2018] for more information about colormap choice for scientific visualization.
EXAMPLES:
Here we plot a couple of simple functions:
sage: complex_plot(sqrt(x), (-5, 5), (-5, 5)) Graphics object consisting of 1 graphics primitive
sage: complex_plot(sin(x), (-5, 5), (-5, 5)) Graphics object consisting of 1 graphics primitive
sage: complex_plot(log(x), (-10, 10), (-10, 10)) Graphics object consisting of 1 graphics primitive
sage: complex_plot(exp(x), (-10, 10), (-10, 10)) Graphics object consisting of 1 graphics primitive
A plot with a different choice of colormap:
sage: complex_plot(exp(x), (-10, 10), (-10, 10), cmap='viridis') Graphics object consisting of 1 graphics primitive
A function with some nice zeros and a pole:
sage: f(z) = z^5 + z - 1 + 1/z sage: complex_plot(f, (-3, 3), (-3, 3)) Graphics object consisting of 1 graphics primitive
The same function as above, but with contours. Contours render poorly with few plot points, so we use 300 here:
sage: f(z) = z^5 + z - 1 + 1/z sage: complex_plot(f, (-3, 3), (-3, 3), plot_points=300, contoured=True) Graphics object consisting of 1 graphics primitive
The same function as above, but tiled and with the plasma colormap:
sage: f(z) = z^5 + z - 1 + 1/z sage: complex_plot(f, (-3, 3), (-3, 3), ....: plot_points=300, tiled=True, cmap='plasma') Graphics object consisting of 1 graphics primitive
When using
tiled=True
, the number of phase subdivisions can be controlled by adjustingnphases
. We make the same plot with fewer tilings:sage: f(z) = z^5 + z - 1 + 1/z sage: complex_plot(f, (-3, 3), (-3, 3), plot_points=300, ....: tiled=True, nphases=5, cmap='plasma') Graphics object consisting of 1 graphics primitive
It is also possible to use linear contours. We plot the same function above on an inset, setting contours to appear \(1\) apart:
sage: f(z) = z^5 + z - 1 + 1/z sage: complex_plot(f, (0, 1), (0, 1), plot_points=300, ....: contoured=True, contour_type='linear', contour_base=1) Graphics object consisting of 1 graphics primitive
Note that tightly spaced contours can lead to Moiré patterns and aliasing problems. For example:
sage: f(z) = z^5 + z - 1 + 1/z sage: complex_plot(f, (-3, 3), (-3, 3), plot_points=300, ....: contoured=True, contour_type='linear', contour_base=1) Graphics object consisting of 1 graphics primitive
When choosing colormaps, cyclic colormaps such as twilight or hsv might be considered more appropriate for showing changes in phase without sharp color contrasts:
sage: f(z) = z^5 + z - 1 + 1/z sage: complex_plot(f, (-3, 3), (-3, 3), plot_points=300, cmap='twilight') Graphics object consisting of 1 graphics primitive
Passing matplotlib as the colormap gives a special colormap that is similar to the default:
sage: f(z) = z^5 + z - 1 + 1/z sage: complex_plot(f, (-3, 3), (-3, 3), ....: plot_points=300, contoured=True, cmap='matplotlib') Graphics object consisting of 1 graphics primitive
Here is the identity, useful for seeing what values map to what colors:
sage: complex_plot(lambda z: z, (-3, 3), (-3, 3)) Graphics object consisting of 1 graphics primitive
The Riemann Zeta function:
sage: complex_plot(zeta, (-30,30), (-30,30)) Graphics object consisting of 1 graphics primitive
For advanced usage, it is possible to tweak many parameters. Increasing
dark_rate
will make regions become darker/lighter faster when there are no contours:sage: complex_plot(zeta, (-30, 30), (-30, 30), dark_rate=1.0) Graphics object consisting of 1 graphics primitive
Decreasing
dark_rate
has the opposite effect. When there are contours, adjustdark_rate
affects how visible contours are. Compare:sage: complex_plot(zeta, (-1, 9), (10, 20), plot_points=200, # long time ....: contoured=True, cmap='twilight', dark_rate=0.2) Graphics object consisting of 1 graphics primitive
and:
sage: complex_plot(zeta, (-1, 9), (10, 20), plot_points=200, # long time ....: contoured=True, cmap='twilight', dark_rate=0.75) Graphics object consisting of 1 graphics primitive
In practice, different values of
dark_rate
will work well with different colormaps.Extra options will get passed on to show(), as long as they are valid:
sage: complex_plot(lambda z: z, (-3, 3), (-3, 3), figsize=[1,1]) Graphics object consisting of 1 graphics primitive
sage: complex_plot(lambda z: z, (-3, 3), (-3, 3)).show(figsize=[1,1]) # These are equivalent
REFERENCES:
Plotting complex functions with colormaps follows the strategy from [LD2021] and incorporates contour techniques described in [WegSem2010].
- sage.plot.complex_plot.complex_to_cmap_rgb(z_values, cmap='turbo', contoured=False, tiled=False, contour_type='logarithmic', contour_base=None, dark_rate=0.5, nphases=10)#
Convert a grid of complex numbers to a grid of rgb values using colors taken from given colormap.
INPUT:
z_values
– A grid of complex numbers, as a list of listscmap
– the string name of a matplotlib colormap, or an instance of a matplotlib Colormap (default:'turbo'
).contoured
– boolean (default:False
); causes magnitude to be indicated through contour-like adjustments to lightness.tiled
– boolean (default:False
); causes magnitude and argument to be indicated through contour-like adjustments to lightness.nphases
– a positive integer (default: \(10\)); whentiled=True
, this is the number of divisions the phase is divided into.contour_type
– either'logarithmic'
, or'linear'
(default:'logarithmic'
); causes added contours to be of given type whencontoured=True
.contour_base
– a positive integer; whencontour_type
is'logarithmic'
, this sets logarithmic contours at multiples ofcontour_base
apart. Whencontour_type
is'linear'
, this sets contours at distances ofcontour_base
apart. IfNone
, then a default is chosen depending oncontour_type
.dark_rate
– a positive number (default: \(0.5\)); affects how quickly magnitudes affect how light/dark the image is. When there are contours, this affects how visible each contour is. Large values (near \(1.0\)) have very strong, immediate effects, while small values (near \(0.0\)) have gradual effects.
OUTPUT:
An \(N \times M \times 3\) floating point Numpy array
X
, whereX[i,j]
is an (r, g, b) tuple.EXAMPLES:
We can call this on grids of complex numbers:
sage: from sage.plot.complex_plot import complex_to_cmap_rgb sage: complex_to_cmap_rgb([[0, 1, 1000]]) # abs tol 1e-4 array([[[0. , 0. , 0. ], [0.49669808, 0.76400071, 0.18024425], [0.87320419, 0.99643856, 0.72730967]]]) sage: complex_to_cmap_rgb([[0, 1, 1000]], cmap='viridis') # abs tol 1e-4 array([[[0. , 0. , 0. ], [0.0984475 , 0.4375291 , 0.42487821], [0.68959896, 0.84592555, 0.84009311]]])
We can change contour types and the distances between contours:
sage: complex_to_cmap_rgb([[0, 1 + 1j, 3 + 4j]], contoured=True, # abs tol 1e-4 ....: contour_type="logarithmic", contour_base=3) array([[[0.64362 , 0.98999 , 0.23356 ], [0.93239357, 0.81063338, 0.21955399], [0.95647342, 0.74861225, 0.14963982]]]) sage: complex_to_cmap_rgb([[0, 1 + 1j, 3 + 4j]], cmap='turbo', # abs tol 1e-4 ....: contoured=True, contour_type="linear", contour_base=3) array([[[0.71246796, 0.9919238 , 0.3816262 ], [0.92617785, 0.79322304, 0.14779989], [0.95156284, 0.72025117, 0.05370383]]])
We see that changing
dark_rate
affects how visible contours are. In this example, we setcontour_base=5
and note that the points \(0\) and \(1 + i\) are far away from contours, but \(2.9 + 4i\) is near (and just below) a contour. Raisingdark_rate
should have strong effects on the last coloration and weaker effects on the others:sage: complex_to_cmap_rgb([[0, 1 + 1j, 2.9 + 4j]], cmap='turbo', # abs tol 1e-4 ....: contoured=True, dark_rate=0.05, contour_base=5) array([[[0.64362 , 0.98999 , 0.23356 ], [0.93334746, 0.81330523, 0.23056563], [0.96357185, 0.75337736, 0.19440913]]]) sage: complex_to_cmap_rgb([[0, 1 + 1j, 2.9 + 4j]], cmap='turbo', # abs tol 1e-4 ....: contoured=True, dark_rate=0.85, contour_base=5) array([[[0.64362 , 0.98999 , 0.23356 ], [0.93874682, 0.82842892, 0.29289564], [0.57778954, 0.42703289, 0.02612716]]])
- sage.plot.complex_plot.complex_to_rgb(z_values, contoured=False, tiled=False, contour_type='logarithmic', contour_base=None, dark_rate=0.5, nphases=10)#
Convert a grid of complex numbers to a grid of rgb values using a default choice of colors.
INPUT:
z_values
– A grid of complex numbers, as a list of listscontoured
– boolean (default:False
); causes magnitude to be indicated through contour-like adjustments to lightness.tiled
– boolean (default:False
); causes magnitude and argument to be indicated through contour-like adjustments to lightness.nphases
– a positive integer (default: \(10\)); whentiled=True
, this is the number of divisions the phase is divided into.contour_type
– either'logarithmic'
, or'linear'
(default:'logarithmic'
); causes added contours to be of given type whencontoured=True
.contour_base
– a positive integer; whencontour_type
is'logarithmic'
, this sets logarithmic contours at multiples ofcontour_base
apart. Whencontour_type
is'linear'
, this sets contours at distances ofcontour_base
apart. IfNone
, then a default is chosen depending oncontour_type
.dark_rate
– a positive number (default: \(0.5\)); affects how quickly magnitudes affect how light/dark the image is. When there are contours, this affects how visible each contour is. Large values (near \(1.0\)) have very strong, immediate effects, while small values (near \(0.0\)) have gradual effects.
OUTPUT:
An \(N \times M \times 3\) floating point Numpy array
X
, whereX[i,j]
is an (r,g,b) tuple.EXAMPLES:
We can call this on grids of complex numbers:
sage: from sage.plot.complex_plot import complex_to_rgb sage: complex_to_rgb([[0, 1, 1000]]) # abs tol 1e-4 array([[[0. , 0. , 0. ], [0.77172568, 0. , 0. ], [1. , 0.64421177, 0.64421177]]]) sage: complex_to_rgb([[0, 1j, 1000j]]) # abs tol 1e-4 array([[[0. , 0. , 0. ], [0.38586284, 0.77172568, 0. ], [0.82210588, 1. , 0.64421177]]]) sage: complex_to_rgb([[0, 1, 1000]], contoured=True) # abs tol 1e-4 array([[[1. , 0. , 0. ], [1. , 0.15 , 0.15 ], [0.66710786, 0. , 0. ]]]) sage: complex_to_rgb([[0, 1, 1000]], tiled=True) # abs tol 1e-4 array([[[1. , 0. , 0. ], [1. , 0.15 , 0.15 ], [0.90855393, 0. , 0. ]]])
We can change contour types and the distances between contours:
sage: complex_to_rgb([[0, 1 + 1j, 3 + 4j]], # abs tol 1e-4 ....: contoured=True, contour_type="logarithmic", contour_base=3) array([[[1. , 0. , 0. ], [0.99226756, 0.74420067, 0. ], [0.91751324, 0.81245954, 0. ]]]) sage: complex_to_rgb([[0, 1 + 1j, 3 + 4j]], # abs tol 1e-4 ....: contoured=True, contour_type="linear", contour_base=3) array([[[1. , 0.15 , 0.15 ], [0.91429774, 0.6857233 , 0. ], [0.81666667, 0.72315973, 0. ]]])
Lowering
dark_rate
causes colors to go to black more slowly near \(0\):sage: complex_to_rgb([[0, 0.5, 1]], dark_rate=0.4) # abs tol 1e-4 array([[[0. , 0. , 0. ], [0.65393731, 0. , 0. ], [0.77172568, 0. , 0. ]]]) sage: complex_to_rgb([[0, 0.5, 1]], dark_rate=0.2) # abs tol 1e-4 array([[[0. , 0. , 0. ], [0.71235886, 0. , 0. ], [0.77172568, 0. , 0. ]]])
- sage.plot.complex_plot.hls_to_rgb(hls)#
Convert array of hls values (each in the range \([0, 1]\)) to a numpy array of rgb values (each in the range \([0, 1]\))
INPUT:
hls
– an \(N \times 3\) array of floats in the range \([0, 1]\); the hls values at each point. (Note that the input can actually be of any dimension, such as \(N \times M \times 3\), as long as the last dimension has length \(3\)).
OUTPUT:
An \(N \times 3\) Numpy array of floats in the range \([0, 1]\), with the same dimensions as the input array.
See also
EXAMPLES:
We convert a row of floats and verify that we can convert back using
rgb_to_hls
:sage: from sage.plot.complex_plot import rgb_to_hls, hls_to_rgb sage: hls = [[0.2, 0.4, 0.5], [0.1, 0.3, 1.0]] sage: rgb = hls_to_rgb(hls) sage: rgb # abs tol 1e-4 array([[0.52, 0.6 , 0.2 ], [0.6 , 0.36, 0. ]]) sage: rgb_to_hls(rgb) # abs tol 1e-4 array([[0.2, 0.4, 0.5], [0.1, 0.3, 1. ]])
Multidimensional inputs can be given as well:
sage: multidim_arr = [[[0, 0.2, 0.4], [0, 1, 0]], [[0, 0, 0], [0.5, 0.6, 0.9]]] sage: hls_to_rgb(multidim_arr) # abs tol 1e-4 array([[[0.28, 0.12, 0.12], [1. , 1. , 1. ]], [[0. , 0. , 0. ], [0.24, 0.96, 0.96]]])
- sage.plot.complex_plot.rgb_to_hls(rgb)#
Convert array of rgb values (each in the range \([0, 1]\)) to a numpy array of hls values (each in the range \([0, 1]\))
INPUT:
rgb
– an \(N \times 3\) array of floats with values in the range \([0, 1]\); the rgb values at each point. (Note that the input can actually be of any dimension, such as \(N \times M \times 3\), as long as the last dimension has length \(3\)).
OUTPUT:
An \(N \times 3\) Numpy array of floats in the range \([0, 1]\), with the same dimensions as the input array.
See also
EXAMPLES:
We convert a row of floats and verify that we can convert back using
hls_to_rgb
:sage: from sage.plot.complex_plot import rgb_to_hls, hls_to_rgb sage: rgb = [[0.2, 0.4, 0.5], [0.1, 0.3, 1.0]] sage: hls = rgb_to_hls(rgb) sage: hls # abs tol 1e-4 array([[0.55555556, 0.35 , 0.42857143], [0.62962963, 0.55 , 1. ]]) sage: hls_to_rgb(hls) # abs tol 1e-4 array([[0.2, 0.4, 0.5], [0.1, 0.3, 1. ]])
Multidimensional inputs can be given as well:
sage: multidim_arr = [[[0, 0.2, 0.4], [1, 1, 1]], [[0, 0, 0], [0.5, 0.6, 0.9]]] sage: rgb_to_hls(multidim_arr) # abs tol 1e-4 array([[[0.58333333, 0.2 , 1. ], [0. , 1. , 0. ]], [[0. , 0. , 0. ], [0.625 , 0.7 , 0.66666667]]])