Functions

spb.functions.plot(*args, **kwargs)[source]

Plots a function of a single variable as a curve.

Typical usage examples are in the followings:

  • Plotting a single expression with a single range.

    plot(expr, range, **kwargs)

  • Plotting a single expression with custom rendering options.

    plot(expr, range, rendering_kw, **kwargs)

  • Plotting a single expression with the default range (-10, 10).

    plot(expr, **kwargs)

  • Plotting multiple expressions with a single range.

    plot(expr1, expr2, …, range, **kwargs)

  • Plotting multiple expressions with multiple ranges.

    plot((expr1, range1), (expr2, range2), …, **kwargs)

  • Plotting multiple expressions with custom labels and rendering options.

    plot((expr1, range1, label1, rendering_kw1), (expr2, range2, label2, rendering_kw2), …, **kwargs)

Parameters
args
exprExpr or callable

It can either be a:

  • Symbolic expression representing the function of one variable to be plotted.

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

range(symbol, min, max)

A 3-tuple denoting the range of the x variable. Default values: min=-10 and max=10.

labelstr, optional

The label to be shown in the legend. If not provided, the string representation of expr 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. Refer to the plotting library (backend) manual for more informations.

adaptivebool, optional

The default value is set to True, which uses the adaptive algorithm implemented in 1 to create smooth plots. Use adaptive_goal and loss_fn to further customize the output.

Set adaptive to False and specify n if uniform sampling is required.

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 1 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.

axis_center(float, float), optional

Tuple of two floats denoting the coordinates of the center or {‘center’, ‘auto’}. Only available with MatplotlibBackend.

backendPlot, optional

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

color_funccallable, optional

A function of 2 variables, x, y (the points computed by the internal algorithm) which defines the line color. Default to None.

detect_polesboolean

Chose whether to detect and correctly plot poles. Defaulto to False. To improve detection, increase the number of discretization points n and/or change the value of eps.

epsfloat

An arbitrary small value used by the detect_poles algorithm. Default value to 0.1. Before changing this value, it is recommended to increase the number of discretization points.

is_pointboolean, optional

Default to False, which will render a line connecting all the points. If True, a scatter plot will be generated.

is_filledboolean, optional

Default to True, which will render empty circular markers. It only works if is_point=True. If False, filled circular markers will be rendered.

labelstr or list/tuple, optional

The label to be shown in the legend. 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 1 for more information. Specifically, look at adaptive.learner.learner1D to find more loss functions.

nint, optional

Used when the adaptive=False: the function is uniformly sampled at n number of points. Default value to 1000. If the adaptive=True, this parameter will be ignored.

only_integersboolean, optional

Default to False. If True, discretize the domain with integer numbers, which can be useful to plot sums. It only works when adaptive=False. When only_integers=True, the number of discretization points is choosen by the algorithm.

paramsdict

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 iplot.

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. 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 expressions.

is_polarboolean, optional

Default to False. If True, requests the backend to use a 2D polar chart.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

stepsboolean, optional

Default to False. If True, connects consecutive points with steps rather than straight segments.

sum_boundint, optional

When plotting sums, the expression will be pre-processed in order to replace lower/upper bounds set to +/- infinity with this +/- numerical value. Default value to 1000. Note: the higher this number, the slower the evaluation.

titlestr, optional

Title of the plot.

tx, tycallable, optional

Apply a numerical function to the discretized x-direction or to the output of the numerical evaluation, the y-direction.

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.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

xscale‘linear’ or ‘log’, optional

Sets the scaling of the x-axis. Default to ‘linear’.

yscale‘linear’ or ‘log’, optional

Sets the scaling of the y-axis. Default to ‘linear’.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart. Note that the function is still being evaluated over the specified range.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart.

References

1(1,2,3)

https://github.com/python-adaptive/adaptive

Examples

>>> from sympy import symbols, sin, pi, tan, exp, cos, log
>>> from spb import plot
>>> x, y = symbols('x, y')

(Source code)

Single Plot

plot(x**2, (x, -5, 5))

(Source code, png, hires.png, pdf)

../_images/functions-2.png

Multiple functions over the same range with custom rendering options:

>>> plot(x, log(x), exp(x), (x, -3, 3), aspect="equal", ylim=(-3, 3),
...    rendering_kw=[{}, {"linestyle": "--"}, {"linestyle": ":"}])
Plot object containing:
[0]: cartesian line: x for x over (-3.0, 3.0)
[1]: cartesian line: log(x) for x over (-3.0, 3.0)
[2]: cartesian line: exp(x) for x over (-3.0, 3.0)

(Source code, png, hires.png, pdf)

../_images/functions-3.png

Plotting a summation in which the free symbol of the expression is not used in the lower/upper bounds:

>>> from sympy import Sum, oo, latex
>>> expr = Sum(1 / x ** y, (x, 1, oo))
>>> plot(expr, (y, 2, 10), sum_bound=1e03, title="$%s$" % latex(expr))
Plot object containing:
[0]: cartesian line: Sum(x**(-y), (x, 1, 1000)) for y over (2.0, 10.0)

(Source code, png, hires.png, pdf)

../_images/functions-4.png

Plotting a summation in which the free symbol of the expression is used in the lower/upper bounds. Here, the discretization variable must assume integer values:

>>> expr = Sum(1 / x, (x, 1, y))
>>> plot(expr, (y, 2, 10), adaptive=False, only_integers=True,
...     is_point=True, is_filled=True, title="$%s$" % latex(expr))
Plot object containing:
[0]: cartesian line: Sum(1/x, (x, 1, y)) for y over (2.0, 10.0)

(Source code, png, hires.png, pdf)

../_images/functions-5.png

Detect singularities and apply a transformation function to the discretized domain in order to convert radians to degrees:

>>> import numpy as np
>>> plot(tan(x), (x, -1.5*pi, 1.5*pi), adaptive_goal=0.001,
...      detect_poles=True, tx=np.rad2deg, ylim=(-7, 7),
...      xlabel="x [deg]")
Plot object containing:
[0]: cartesian line: tan(x) for x over (-10.0, 10.0)

(Source code, png, hires.png, pdf)

../_images/functions-6.png

Advanced example showing:

  • detect singularities by setting adaptive=False (better performance), increasing the number of discretization points (in order to have ‘vertical’ segments on the lines) and reducing the threshold for the singularity-detection algorithm.

  • application of color function.

>>> import numpy as np
>>> expr = 1 / cos(10 * x) + 5 * sin(x)
>>> def cf(x, y):
...     # map a colormap to the distance from the origin
...     d = np.sqrt(x**2 + y**2)
...     # visibility of the plot is limited: ylim=(-10, 10). However,
...     # some of the y-values computed by the function are much higher
...     # (or lower). Filter them out in order to have the entire
...     # colormap spectrum visible in the plot.
...     offset = 12 # 12 > 10 (safety margin)
...     d[(y > offset) | (y < -offset)] = 0
...     return d
>>> p1 = plot(expr, (x, -5, 5),
...         "distance from (0, 0)", {"cmap": "plasma"},
...         ylim=(-10, 10), adaptive=False, detect_poles=True, n=3e04,
...         eps=1e-04, color_func=cf, title="$%s$" % latex(expr))

(Source code, png, hires.png, pdf)

../_images/functions-7.png

Combining multiple plots together:

>>> p2 = plot(5 * sin(x), (x, -5, 5), {"linestyle": "--"}, show=False)
>>> (p1 + p2).show()

(Source code, png, hires.png, pdf)

../_images/functions-8.png

Plotting a numerical function instead of a symbolic expression:

>>> import numpy as np
>>> plot(lambda t: np.cos(np.exp(-t)), ("t", -pi, 0))

(Source code, png, hires.png, pdf)

../_images/functions-9.png

Interactive-widget plot of an oscillator. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
x, a, b, c = symbols("x, a, b, c")
plot(
    (cos(a * x + b) * exp(-c * x), "oscillator"),
    (exp(-c * x), "upper limit", {"linestyle": ":"}),
    (-exp(-c * x), "lower limit", {"linestyle": ":"}),
    (x, 0, 2 * pi),
    params={
        a: (1, 0, 10),     # frequency
        b: (0, 0, 2 * pi), # phase
        c: (0.25, 0, 1)    # damping
    },
    ylim=(-1.25, 1.25)
)
spb.functions.plot_parametric(*args, **kwargs)[source]

Plots a 2D parametric curve.

Typical usage examples are in the followings:

  • Plotting a single parametric curve with a range

    plot_parametric(expr_x, expr_y, range)

  • Plotting multiple parametric curves with the same range

    plot_parametric((expr_x, expr_y), …, range)

  • Plotting multiple parametric curves with different ranges

    plot_parametric((expr_x, expr_y, range), …)

  • Plotting multiple curves with different ranges and custom labels

    plot_parametric((expr_x, expr_y, range, label), …)

Parameters
args
expr_xExpr

The expression representing x component of the parametric function. It can be a:

  • Symbolic expression representing the function of one variable to be plotted.

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

expr_yExpr

The expression representing y component of the parametric function. It can be a:

  • Symbolic expression representing the function of one variable to be plotted.

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

range(symbol, min, max)

A 3-tuple denoting the parameter symbol, start and stop. For example, (u, 0, 5). If the range is not specified, then a default range of (-10, 10) is used.

However, if the arguments are specified as (expr_x, expr_y, range), …, you must specify the ranges for each expressions manually.

labelstr, optional

The label to be shown in the legend. If not provided, the string representation of expr_x and expr_y 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. Refer to the plotting library (backend) manual for more informations.

adaptivebool, optional

The default value is set to True, which uses the adaptive algorithm implemented in 2 to create smooth plots. Use adaptive_goal and loss_fn to further customize the output.

Set adaptive to False and specify n if uniform sampling is required.

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.

axis_center(float, float), optional

Tuple of two floats denoting the coordinates of the center or {‘center’, ‘auto’}. Only available with MatplotlibBackend.

backendPlot, optional

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

color_funccallable, optional

A function defining the line color. The arity can be:

  • 1 argument: f(t), where t is the parameter.

  • 2 arguments: f(x, y) where x, y are the coordinates of the points.

  • 3 arguments: f(x, y, t).

Default to None.

labelstr or list/tuple, optional

The label to be shown in the legend or in the colorbar. 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.

nint, optional

Used when the adaptive is set to False. The function is uniformly sampled at n number of points. Default value to 1000. If the adaptive flag is set to True, this parameter will be ignored.

paramsdict

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 iplot.

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. 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 expressions.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

titlestr, optional

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

tx, ty, tpcallable, optional

Apply a numerical function to the x-direction, y-direction and parameter, respectively.

use_cmboolean, optional

If True, apply a color map to the parametric lines. If False, solid colors will be used instead. Default to True.

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.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

xscale‘linear’ or ‘log’, optional

Sets the scaling of the x-axis. Default to ‘linear’.

yscale‘linear’ or ‘log’, optional

Sets the scaling of the y-axis. Default to ‘linear’.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart.

References

2(1,2,3)

https://github.com/python-adaptive/adaptive

Examples

>>> from sympy import symbols, cos, sin, pi
>>> from spb import plot_parametric
>>> t, u, v = symbols('t, u, v')

(Source code)

A parametric plot of a single expression (a Hypotrochoid using an equal aspect ratio):

>>> plot_parametric(
...      2 * cos(u) + 5 * cos(2 * u / 3),
...      2 * sin(u) - 5 * sin(2 * u / 3),
...      (u, 0, 6 * pi), aspect="equal")
Plot object containing:
[0]: parametric cartesian line: (5*cos(2*u/3) + 2*cos(u), -5*sin(2*u/3) + 2*sin(u)) for u over (0.0, 18.84955592153876)

(Source code, png, hires.png, pdf)

../_images/functions-11.png

A parametric plot with multiple expressions with the same range with solid line colors:

>>> plot_parametric((2 * cos(t), sin(t)), (cos(t), 2 * sin(t)),
...    (t, 0, 2*pi), use_cm=False)
Plot object containing:
[0]: parametric cartesian line: (2*cos(t), sin(t)) for t over (0.0, 6.283185307179586)
[1]: parametric cartesian line: (cos(t), 2*sin(t)) for t over (0.0, 6.283185307179586)

(Source code, png, hires.png, pdf)

../_images/functions-12.png

A parametric plot with multiple expressions with different ranges, custom labels, custom rendering options and a transformation function applied to the discretized parameter to convert radians to degrees:

>>> import numpy as np
>>> plot_parametric(
...      (3 * cos(u), 3 * sin(u), (u, 0, 2 * pi), "u [deg]", {"lw": 3}),
...      (3 * cos(2 * v), 5 * sin(4 * v), (v, 0, pi), "v [deg]"),
...      aspect="equal", tp=np.rad2deg)
Plot object containing:
[0]: parametric cartesian line: (3*cos(u), 3*sin(u)) for u over (0.0, 6.283185307179586)
[1]: parametric cartesian line: (3*cos(2*u), 5*sin(4*u)) for u over (0.0, 3.141592653589793)

(Source code, png, hires.png, pdf)

../_images/functions-13.png

Plotting a numerical function instead of a symbolic expression:

>>> import numpy as np
>>> fx = lambda t: np.sin(t) * (np.exp(np.cos(t)) - 2 * np.cos(4 * t) - np.sin(t / 12)**5)
>>> fy = lambda t: np.cos(t) * (np.exp(np.cos(t)) - 2 * np.cos(4 * t) - np.sin(t / 12)**5)
>>> plot_parametric(fx, fy, ("t", 0, 12 * pi), title="Butterfly Curve",
...     use_cm=False)

(Source code, png, hires.png, pdf)

../_images/functions-14.png

Interactive-widget plot. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
x, a = symbols("x a")
plot_parametric(
    cos(a * x), sin(x), (x, 0, 2*pi),
    params={a: (1, 0, 2)},
    aspect="equal", xlim=(-1.25, 1.25), ylim=(-1.25, 1.25)
)
spb.functions.plot_parametric_region(*args, **kwargs)[source]

Plots a 2D parametric region.

NOTE: this is an experimental plotting function as it only draws lines without fills. The resulting visualization might change when new features will be implemented.

Typical usage examples are in the followings:

  • Plotting a single parametric curve with a range

    plot_parametric(expr_x, expr_y, range_u, range_v)

  • Plotting multiple parametric curves with the same range

    plot_parametric((expr_x, expr_y), …, range_u, range_v)

  • Plotting multiple parametric curves with different ranges

    plot_parametric((expr_x, expr_y, range_u, range_v), …)

Parameters
args
expr_x, expr_yExpr

The expression representing x and y component, respectively, of the parametric function. It can be a:

  • Symbolic expression representing the function of one variable to be plotted.

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

range_u, range_v(symbol, min, max)

A 3-tuple denoting the parameter symbols, start and stop. For example, (u, 0, 5), (v, 0, 5). If the ranges are not specified, then they default to (-10, 10).

However, if the arguments are specified as (expr_x, expr_y, range_u, range_v), …, you must specify the ranges for each expressions manually.

rendering_kwdict, optional

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

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.

backendPlot, optional

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

nint, optional

Used when the adaptive is set to False. The function is uniformly sampled at n number of points. Default value to 1000. If the adaptive flag is set to True, this parameter will be ignored.

n1, n2int, optional

Number of lines to create along each direction. Default to 10. Note: the higher the number, the slower the rendering.

rkw_u, rkw_vdict

A dictionary of keywords/values which is passed to the backend’s function to customize the appearance of lines along the u and v directions, respectively. These overrides rendering_kw if provided. Refer to the plotting library (backend) manual for more informations.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

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, ylabelstr, optional

Label for the x-axis or y-axis, respectively.

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

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

xlim, ylim(float, float), optional

Denotes the x-axis or y-axis limits, (min, max), visible in the chart.

Examples

>>> from sympy import symbols, cos, sin, pi, I, re, im, latex
>>> from spb import plot_parametric_region

(Source code)

Plot a slice of a ring, applying the same style to all lines:

>>> r, theta = symbols("r theta")
>>> plot_parametric_region(r * cos(theta), r * sin(theta),
...     (r, 1, 2), (theta, 0, 2*pi/3),
...     {"color": "k", "linewidth": 0.75},
...     n1=5, n2=15, aspect="equal")

(Source code, png, hires.png, pdf)

../_images/functions-16.png

Complex mapping, applying to different line styles:

>>> x, y, z = symbols("x y z")
>>> f = 1 / z**2
>>> f_cart = f.subs(z, x + I * y)
>>> r, i = re(f_cart), im(f_cart)
>>> n1, n2 = 30, 30
>>> plot_parametric_region(r, i, (x, -2, 2), (y, -2, 2),
...     rkw_u={"color": "r", "linewidth": 0.75},
...     rkw_v={"color": "b", "linewidth": 0.75},
...     n1=20, n2=20, aspect="equal", xlim=(-2, 2), ylim=(-2, 2),
...     xlabel="Re", ylabel="Im", title="$f(z)=%s$" % latex(f))

(Source code, png, hires.png, pdf)

../_images/functions-17.png
spb.functions.plot3d(*args, **kwargs)[source]

Plots a 3D surface plot.

Typical usage examples are in the followings:

  • Plotting a single expression.

    plot3d(expr, range_x, range_y, **kwargs)

  • Plotting multiple expressions with the same ranges.

    plot3d(expr1, expr2, range_x, range_y, **kwargs)

  • Plotting multiple expressions with different ranges.

    plot3d((expr1, range_x1, range_y1), (expr2, range_x2, range_y2), …, **kwargs)

  • Plotting multiple expressions with custom labels and rendering options.

    plot3d((expr1, range_x1, range_y1, label1, rendering_kw1), (expr2, range_x2, range_y2, label2, rendering_kw2), …, **kwargs)

Note: it is important to specify at least the range_x, otherwise the function might create a rotated plot.

Parameters
args
exprExpr

Expression representing the function of two variables to be plotted. The expression representing the function of two variables to be plotted. It can be a:

  • Symbolic expression.

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

range_x: (symbol, min, max)

A 3-tuple denoting the range of the x variable. Default values: min=-10 and max=10.

range_y: (symbol, min, max)

A 3-tuple denoting the range of the y variable. Default values: min=-10 and max=10.

labelstr, optional

The label to be shown in the colorbar. If not provided, the string representation of expr will be used.

rendering_kwdict, optional

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

adaptivebool, optional

The default value is set to False, which uses a uniform sampling strategy with number of discretization points n1 and n2 along the x and y directions, respectively.

Set adaptive to True to use the adaptive algorithm implemented in 3 to create smooth plots. Use adaptive_goal and loss_fn to further customize the output.

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 3 for more information.

backendPlot, optional

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

color_funccallable, optional

A function of 3 variables, x, y, z (the points computed by the internal algorithm) which defines the surface color when use_cm=True. Default to None.

is_polarboolean, optional

Default to False. If True, requests a polar discretization. In this case, range_x represents the radius, range_y represents the angle.

labelstr or list/tuple, optional

The label to be shown in the colorbar. 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 3 for more information. Specifically, look at adaptive.learner.learnerND to find more loss functions.

n1, n2int, optional

n1 and n2 set the number of discretization points along the x and y ranges, respectively. Default value to 100.

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

If an integer is provided, the x and y ranges are sampled uniformly at n of points. If a tuple is provided, it overrides n1 and n2.

paramsdict

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 iplot.

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 surfaces. 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 expressions.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

titlestr, optional

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

tx, ty, tzcallable, optional

Apply a numerical function to the discretized domain in the x, y and z direction, respectively.

use_cmboolean, optional

If True, apply a color map to the surface. If False, solid colors will be used instead. Default to False.

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.

wireframeboolean, optional

Enable or disable a wireframe over the surface. Depending on the number of wireframe lines (see wf_n1 and wf_n2), activating this option might add a considerable overhead during the plot’s creation. Default to False (disabled).

wf_n1, wf_n2int, optional

Number of wireframe lines along the x and y ranges, respectively. Default to 10. Note that increasing this number might considerably slow down the plot’s creation.

wf_npointint or None, optional

Number of discretization points for the wireframe lines. Default to None, meaning that each wireframe line will have n1 or n2 number of points, depending on the line direction.

wf_rendering_kwdict, optional

A dictionary of keywords/values which is passed to the backend’s function to customize the appearance of wireframe lines.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

zlabelstr, optional

Label for the z-axis.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart. Note that the function is still being evaluate over range_x.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart. Note that the function is still being evaluate over range_y.

zlim(float, float), optional

Denotes the z-axis limits, (min, max), visible in the chart.

References

3(1,2,3)

https://github.com/python-adaptive/adaptive

Examples

Note: for documentation purposes, the following examples uses Matplotlib. However, Matplotlib’s 3D capabilities are rather limited. Consider running these examples with a different backend (hence, modify the rendering_kw and wf_rendering_kw to pass the correct options to the backend).

>>> from sympy import symbols, cos, sin, pi, exp
>>> from spb import plot3d
>>> x, y = symbols('x y')

(Source code)

Single plot with Matplotlib:

>>> plot3d(cos((x**2 + y**2)), (x, -3, 3), (y, -3, 3))
Plot object containing:
[0]: cartesian surface: cos(x**2 + y**2) for x over (-3.0, 3.0) and y over (-3.0, 3.0)

(Source code, png, hires.png, pdf)

../_images/functions-19.png

Single plot with Plotly, illustrating how to apply:

  • a color map: by default, it will map colors to the z values.

  • wireframe lines to better understand the discretization and curvature.

  • transformation to the discretized ranges in order to convert radians to degrees.

  • custom aspect ratio with Plotly.

from sympy import symbols, sin, cos, pi
from spb import plot3d, PB
import numpy as np
x, y = symbols("x, y")
expr = (cos(x) + sin(x) * sin(y) - sin(x) * cos(y))**2
plot3d(
    expr, (x, 0, pi), (y, 0, 2 * pi), backend=PB, use_cm=True,
    tx=np.rad2deg, ty=np.rad2deg, wireframe=True, wf_n1=20, wf_n2=20,
    xlabel="x [deg]", ylabel="y [deg]",
    aspect=dict(x=1.5, y=1.5, z=0.5))

(Source code, png, html, pdf)

Multiple plots with same range. Set use_cm=True to distinguish the expressions:

>>> plot3d(x*y, -x*y, (x, -5, 5), (y, -5, 5), use_cm=True)
Plot object containing:
[0]: cartesian surface: x*y for x over (-5.0, 5.0) and y over (-5.0, 5.0)
[1]: cartesian surface: -x*y for x over (-5.0, 5.0) and y over (-5.0, 5.0)

(Source code, png, hires.png, pdf)

../_images/functions-21.png

Multiple plots with different ranges and solid colors.

>>> f = x**2 + y**2
>>> p = plot3d((f, (x, -3, 3), (y, -3, 3)),
...     (-f, (x, -5, 5), (y, -5, 5)))
Plot object containing:
[0]: cartesian surface: x**2 + y**2 for x over (-3.0, 3.0) and y over (-3.0, 3.0)
[1]: cartesian surface: -x**2 - y**2 for x over (-5.0, 5.0) and y over (-5.0, 5.0)

(Source code, png, hires.png, pdf)

../_images/functions-22.png

Single plot with a polar discretization, a color function mapping a colormap to the radius. Note that the same result can be achieved with plot3d_revolution.

>>> r, theta = symbols("r, theta")
>>> expr = cos(r**2) * exp(-r / 3)
>>> plot3d(expr, (r, 0, 3.25), (theta, 3 * pi / 2, 2 * pi),
...     "r", {"alpha": 0.4}, is_polar=True, legend=True,
...     use_cm=True, color_func=lambda x, y, z: np.sqrt(x**2 + y**2),
...     wireframe=True, wf_n1=20, wf_n2=10,
...     wf_rendering_kw={"lw": 0.75})

(Source code, png, hires.png, pdf)

../_images/functions-23.png

Plotting a numerical function instead of a symbolic expression:

>>> plot3d(lambda x, y: x * np.exp(-x**2 - y**2),
...     ("x", -3, 3), ("y", -3, 3), use_cm=True)

(Source code, png, hires.png, pdf)

../_images/functions-24.png

Interactive-widget plot. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
x, d = symbols("x d")
plot3d(
    cos(x**2 + y**2) * exp(-(x**2 + y**2) * d), (x, -2, 2), (y, -2, 2),
    params={d: (0.25, 0, 1)}, n=50, zlim=(-1.25, 1.25))
spb.functions.plot3d_parametric_line(*args, **kwargs)[source]

Plots a 3D parametric line plot.

Typical usage examples are in the followings:

  • Plotting a single expression.

    plot3d_parametric_line(expr_x, expr_y, expr_z, range, **kwargs)

  • Plotting a single expression with a custom label and rendering options.

    plot3d_parametric_line(expr_x, expr_y, expr_z, range, label, rendering_kw, **kwargs)

  • Plotting multiple expressions with the same ranges.

    plot3d_parametric_line((expr_x1, expr_y1, expr_z1), (expr_x2, expr_y2, expr_z2), …, range, **kwargs)

  • Plotting multiple expressions with different ranges.

    plot3d_parametric_line((expr_x1, expr_y1, expr_z1, range1), (expr_x2, expr_y2, expr_z2, range2), …, **kwargs)

  • Plotting multiple expressions with custom labels and rendering options.

    plot3d_parametric_line((expr_x1, expr_y1, expr_z1, range1, label1, rendering_kw1), (expr_x2, expr_y2, expr_z2, range2, label1, rendering_kw2), …, **kwargs)

Parameters
args
expr_xExpr

The expression representing x component of the parametric function. It can be a:

  • Symbolic expression representing the function of one variable to be plotted.

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

expr_yExpr

The expression representing y component of the parametric function. It can be a:

  • Symbolic expression representing the function of one variable to be plotted.

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

expr_zExpr

The expression representing z component of the parametric function. It can be a:

  • Symbolic expression representing the function of one variable to be plotted.

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

range(symbol, min, max)

A 3-tuple denoting the range of the parameter variable.

labelstr, optional

An optional string denoting the label of the expression to be visualized on the legend. If not provided, the string representation of the expression 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. Refer to the plotting library (backend) manual for more informations.

adaptivebool, optional

The default value is set to True, which uses the adaptive algorithm implemented in 4 to create smooth plots. Use adaptive_goal and loss_fn to further customize the output.

Set adaptive to False and specify n if uniform sampling is required.

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 4 for more information.

backendPlot, optional

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

color_funccallable, optional

A function defining the line color. The arity can be:

  • 1 argument: f(t), where t is the parameter.

  • 3 arguments: f(x, y, z) where x, y, z are the coordinates of the points.

  • 4 arguments: f(x, y, z, t).

Default to None.

labelstr or list/tuple, optional

The label to be shown in the legend or in the colorbar. 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 4 for more information. Specifically, look at adaptive.learner.learner1D to find more loss functions.

nint, optional

Used when the adaptive is set to False. The function is uniformly sampled at n number of points. Default value to 1000. If the adaptive flag is set to True, this parameter will be ignored.

paramsdict

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 iplot.

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. 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 expressions.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

titlestr, optional

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

tx, ty, tz, tpcallable, optional

Apply a numerical function to the x, y, z directions and to the discretized parameter.

use_cmboolean, optional

If True, apply a color map to the parametric lines. If False, solid colors will be used instead. Default to True.

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.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

zlabelstr, optional

Label for the z-axis.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart.

zlim(float, float), optional

Denotes the z-axis limits, (min, max), visible in the chart.

References

4(1,2,3)

https://github.com/python-adaptive/adaptive

Examples

Note: for documentation purposes, the following examples uses Matplotlib. However, Matplotlib’s 3D capabilities are rather limited. Consider running these examples with a different backend (hence, modify rendering_kw to pass the correct options to the backend).

>>> from sympy import symbols, cos, sin, pi, root
>>> from spb import plot3d_parametric_line
>>> t = symbols('t')

(Source code)

Single plot.

>>> plot3d_parametric_line(cos(t), sin(t), t, (t, -5, 5))
Plot object containing:
[0]: 3D parametric cartesian line: (cos(t), sin(t), t) for t over (-5.0, 5.0)

(Source code, png, hires.png, pdf)

../_images/functions-26.png

Customize the appearance by setting a label to the colorbar, changing the colormap and the line width. Note the use of zlim to force a near-equal aspect ratio with Matplotlib 3D plots.

>>> plot3d_parametric_line(
...     3 * sin(t) + 2 * sin(3 * t), cos(t) - 2 * cos(3 * t), cos(5 * t),
...     (t, 0, 2 * pi), "t [rad]", {"cmap": "hsv", "lw": 1.5},
...     zlim=(-3, 3))
Plot object containing:
[0]: 3D parametric cartesian line: (3*sin(t) + 2*sin(3*t), cos(t) - 2*cos(3*t), cos(5*t)) for t over (0.0, 6.283185307179586)

(Source code, png, hires.png, pdf)

../_images/functions-27.png

Plot multiple parametric 3D lines with different ranges:

>>> a, b, n = 2, 1, 4
>>> p, r, s = symbols("p r s")
>>> xp = a * cos(p) * cos(n * p)
>>> yp = a * sin(p) * cos(n * p)
>>> zp = b * cos(n * p)**2 + pi
>>> xr = root(r, 3) * cos(r)
>>> yr = root(r, 3) * sin(r)
>>> zr = 0
>>> plot3d_parametric_line(
...     (xp, yp, zp, (p, 0, pi if n % 2 == 1 else 2 * pi), "petals"),
...     (xr, yr, zr, (r, 0, 6*pi), "roots"),
...     (-sin(s)/3, 0, s, (s, 0, pi), "stem"), use_cm=False)
Plot object containing:
[0]: 3D parametric cartesian line: (2*cos(p)*cos(4*p), 2*sin(p)*cos(4*p), cos(4*p)**2 + pi) for p over (0.0, 6.283185307179586)
[1]: 3D parametric cartesian line: (r**(1/3)*cos(r), r**(1/3)*sin(r), 0) for r over (0.0, 18.84955592153876)
[2]: 3D parametric cartesian line: (-sin(s)/3, 0, s) for s over (0.0, 3.141592653589793)

(Source code, png, hires.png, pdf)

../_images/functions-28.png

Plotting a numerical function instead of a symbolic expression, using Plotly:

from spb import plot3d_parametric_line, PB
import numpy as np
fx = lambda t: (1 + 0.25 * np.cos(75 * t)) * np.cos(t)
fy = lambda t: (1 + 0.25 * np.cos(75 * t)) * np.sin(t)
fz = lambda t: t + 2 * np.sin(75 * t)
plot3d_parametric_line(fx, fy, fz, ("t", 0, 6 * np.pi),
    {"line": {"colorscale": "bluered"}},
    title="Helical Toroid", backend=PB, adaptive=False, n=1e04)

(Source code, png, html, pdf)

Interactive-widget plot of the parametric line over a tennis ball. Refer to iplot documentation to learn more about the params dictionary.

import k3d
a, b = symbols("a, b")
c = 2 * sqrt(a * b)
r = a + b
params = {a: (1.5, 0, 2), b: (1, 0, 2)}
sphere = plot3d_revolution(
    (r * cos(t), r * sin(t)), (t, 0, pi),
    params=params, n=50, parallel_axis="x",
    backend=KB,
    show_curve=False, show=False,
    rendering_kw={"color":0x353535})
line = plot3d_parametric_line(
    a * cos(t) + b * cos(3 * t),
    a * sin(t) - b * sin(3 * t),
    c * sin(2 * t), (t, 0, 2*pi),
    {"color_map": k3d.matplotlib_color_maps.Summer}, params=params,
    backend=KB, show=False)
(line + sphere).show()
spb.functions.plot3d_parametric_surface(*args, **kwargs)[source]

Plots a 3D parametric surface plot.

Typical usage examples are in the followings:

  • Plotting a single expression.

    plot3d_parametric_surface(expr_x, expr_y, expr_z, range_u, range_v, label, **kwargs)

  • Plotting multiple expressions with the same ranges.

    plot3d_parametric_surface((expr_x1, expr_y1, expr_z1), (expr_x2, expr_y2, expr_z2), range_u, range_v, **kwargs)

  • Plotting multiple expressions with different ranges.

    plot3d_parametric_surface((expr_x1, expr_y1, expr_z1, range_u1, range_v1), (expr_x2, expr_y2, expr_z2, range_u2, range_v2), **kwargs)

  • Plotting multiple expressions with different ranges and rendering option.

    plot3d_parametric_surface((expr_x1, expr_y1, expr_z1, range_u1, range_v1, label1, rendering_kw1), (expr_x2, expr_y2, expr_z2, range_u2, range_v2, label2, rendering_kw2), **kwargs)

Note: it is important to specify both the ranges.

Parameters
args
expr_x: Expr

Expression representing the function along x. It can be a:

  • Symbolic expression.

  • Numerical function of two variable, f(u, v), supporting vectorization. In this case the following keyword arguments are not supported: params.

expr_y: Expr

Expression representing the function along y. It can be a:

  • Symbolic expression.

  • Numerical function of two variable, f(u, v), supporting vectorization. In this case the following keyword arguments are not supported: params.

expr_z: Expr

Expression representing the function along z. It can be a:

  • Symbolic expression.

  • Numerical function of two variable, f(u, v), supporting vectorization. In this case the following keyword arguments are not supported: params.

range_u: (symbol, min, max)

A 3-tuple denoting the range of the u variable.

range_v: (symbol, min, max)

A 3-tuple denoting the range of the v variable.

labelstr, optional

The label to be shown in the colorbar. If not provided, the string representation of the expression will be used.

rendering_kwdict, optional

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

backendPlot, optional

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

color_funccallable, optional

A function defining the surface color when use_cm=True. The arity can be:

  • 1 argument: f(u), where u is the first parameter.

  • 2 arguments: f(u, v) where u, v are the parameters.

  • 3 arguments: f(x, y, z) where x, y, z are the coordinates of the points.

  • 5 arguments: f(x, y, z, u, v).

Default to None.

labelstr or list/tuple, optional

The label to be shown in the colorbar. If not provided, the string representation will be used. The number of labels must be equal to the number of expressions.

n1, n2int, optional

n1 and n2 set the number of discretization points along the u and v ranges, respectively. Default value to 100.

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

If an integer is provided, the u and v ranges are sampled uniformly at n of points. If a tuple is provided, it overrides n1 and n2.

paramsdict

A dictionary mapping symbols to parameters. This keyword argument enables the interactive-widgets plot. Learn more by reading the documentation of iplot.

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 surfaces. 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 expressions.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

titlestr, optional

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

tx, ty, tzcallable, optional

Apply a numerical function to the discretized domain in the x, y and z direction, respectively.

use_cmboolean, optional

If True, apply a color map to the surface. If False, solid colors will be used instead. Default to False.

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.

wireframeboolean, optional

Enable or disable a wireframe over the surface. Depending on the number of wireframe lines (see wf_n1 and wf_n2), activating this option might add a considerable overhead during the plot’s creation. Default to False (disabled).

wf_n1, wf_n2int, optional

Number of wireframe lines along the u and v ranges, respectively. Default to 10. Note that increasing this number might considerably slow down the plot’s creation.

wf_npointint or None, optional

Number of discretization points for the wireframe lines. Default to None, meaning that each wireframe line will have n1 or n2 number of points, depending on the line direction.

wf_rendering_kwdict, optional

A dictionary of keywords/values which is passed to the backend’s function to customize the appearance of wireframe lines.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

zlabelstr, optional

Label for the z-axis.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart.

zlim(float, float), optional

Denotes the z-axis limits, (min, max), visible in the chart.

Examples

Note: for documentation purposes, the following examples uses Matplotlib. However, Matplotlib’s 3D capabilities are rather limited. Consider running these examples with a different backend (hence, modify the rendering_kw and wf_rendering_kw to pass the correct options to the backend).

>>> from sympy import symbols, cos, sin, pi, I, sqrt, atan2, re, im
>>> from spb import plot3d_parametric_surface
>>> u, v = symbols('u v')

(Source code)

Plot a parametric surface:

>>> plot3d_parametric_surface(
...     u * cos(v), u * sin(v), u * cos(4 * v) / 2,
...     (u, 0, pi), (v, 0, 2*pi),
...     use_cm=False, title="Sinusoidal Cone")
Plot object containing:
[0]: parametric cartesian surface: (u*cos(v), u*sin(v), u*cos(4*v)/2) for u over (0.0, 3.141592653589793) and v over (0.0, 6.283185307179586)

(Source code, png, hires.png, pdf)

../_images/functions-31.png

Customize the appearance of the surface by changing the colormap. Apply a color function mapping the v values. Activate the wireframe to better visualize the parameterization.

>>> x = (1 + v / 2 * cos(u / 2)) * cos(u)
>>> y = (1 + v / 2 * cos(u / 2)) * sin(u)
>>> z = v / 2 * sin(u / 2)
>>> plot3d_parametric_surface(
...     x, y, z, (u, 0, 2*pi), (v, -1, 1),
...     "v", {"alpha": 0.75, "cmap": "twilight"},
...     use_cm=True, color_func=lambda u, v: u,
...     title="Möbius strip",
...     wireframe=True, wf_n1=20, wf_rendering_kw={"lw": 0.75})

(Source code, png, hires.png, pdf)

../_images/functions-32.png

Riemann surfaces of the real part of the multivalued function z**n, using Plotly:

from sympy import symbols, sqrt, re, im, pi, atan2, sin, cos, I
from spb import plot3d_parametric_surface, PB
r, theta, x, y = symbols("r, theta, x, y", real=True)
mag = lambda z: sqrt(re(z)**2 + im(z)**2)
phase = lambda z, k=0: atan2(im(z), re(z)) + 2 * k * pi
n = 2 # exponent (integer)
z = x + I * y # cartesian
d = {x: r * cos(theta), y: r * sin(theta)} # cartesian to polar
branches = [(mag(z)**(1 / n) * cos(phase(z, i) / n)).subs(d)
    for i in range(n)]
exprs = [(r * cos(theta), r * sin(theta), rb) for rb in branches]
plot3d_parametric_surface(*exprs, (r, 0, 3), (theta, -pi, pi),
    backend=PB, wireframe=True, wf_n2=20, zlabel="f(z)")

(Source code, png, html, pdf)

Plotting a numerical function instead of a symbolic expression. Note the use of zlim to force a near-equal aspect ratio with Matplotlib 3D plots.

>>> import numpy as np
>>> fx = lambda u, v: (4 + np.cos(u)) * np.cos(v)
>>> fy = lambda u, v: (4 + np.cos(u)) * np.sin(v)
>>> fz = lambda u, v: np.sin(u)
>>> plot3d_parametric_surface(fx, fy, fz, ("u", 0, 2 * pi),
...     ("v", 0, 2 * pi), zlim=(-2.5, 2.5), title="Torus")
Plot object containing:
[0]: parametric cartesian surface: (<function <lambda> at 0x7f466b8b2950>, <function <lambda> at 0x7f466b8b29e0>, <function <lambda> at 0x7f466b8b2a70>) for u over (0.0, 6.283185307179586) and v over (0.0, 6.283185307179586)

(Source code, png, hires.png, pdf)

../_images/functions-34.png

Interactive-widget plot. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
import k3d
alpha, u, v = symbols("alpha u v")
plot3d_parametric_surface((
       exp(u) * cos(v - alpha) / 2 + exp(-u) * cos(v + alpha) / 2,
       exp(u) * sin(v - alpha) / 2 + exp(-u) * sin(v + alpha) / 2,
       cos(alpha) * u + sin(alpha) * v
   ),
   (u, -1, 1), (v, 0, 2 * pi),
   backend=KB,
   use_cm=True,
   color_func=lambda u, v: v,
   rendering_kw={"color_map": k3d.colormaps.paraview_color_maps.Hue_L60},
   wireframe=True, wf_n2=15, wf_rendering_kw={"width": 0.0025},
   grid=False, n=50,
   params={alpha: (0, 0, pi)},
   title="Catenoid \, to \, Right \, Helicoid \, Transformation")

Interactive-widget plot. Refer to iplot documentation to learn more about the params dictionary. Note that the plot’s creation might be slow due to the wireframe lines.

from sympy import *
from spb import *
import param
n, u, v = symbols("n, u, v")
x = v * cos(u)
y = v * sin(u)
z = sin(n * u)
plot3d_parametric_surface(
    (x, y, z, (u, 0, 2*pi), (v, -1, 0)),
    params = {
        n: param.Integer(2, label="n")
    },
    backend=KB,
    use_cm=True,
    title=r"Plücker's \, conoid",
    wireframe=True,
    wf_rendering_kw={"width": 0.004},
    wf_n1=75, wf_n2=6
)
spb.functions.plot3d_spherical(*args, **kwargs)[source]

Plots a radius as a function of the spherical coordinates theta and phi.

Typical usage examples are in the followings:

  • Plotting a single expression.

    plot3d_spherical(r, range_theta, range_phi, **kwargs)

  • Plotting multiple expressions with the same ranges.

    plot3d_parametric_surface(r1, r2, range_theta, range_phi, **kwargs)

  • Plotting multiple expressions with different ranges.

    plot3d_parametric_surface((r1, range_theta1, range_phi1), (r2, range_theta2, range_phi2), **kwargs)

  • Plotting multiple expressions with different ranges and rendering option.

    plot3d_parametric_surface((r1, range_theta1, range_phi1, label1, rendering_kw1), (r2, range_theta2, range_phi2, label2, rendering_kw2), **kwargs)

Note: it is important to specify both the ranges.

Parameters
args
r: Expr

Expression representing the radius. It can be a:

  • Symbolic expression.

  • Numerical function of two variable, f(theta, phi), supporting vectorization. In this case the following keyword arguments are not supported: params.

theta: (symbol, min, max)

A 3-tuple denoting the range of the polar angle, which is limited in [0, pi]. Consider a sphere:

  • theta=0 indicates the north pole.

  • theta=pi/2 indicates the equator.

  • theta=pi indicates the south pole.

range_v: (symbol, min, max)

A 3-tuple denoting the range of the azimuthal angle, which is limited in [0, 2*pi].

labelstr, optional

The label to be shown in the colorbar. If not provided, the string representation of the expression will be used.

rendering_kwdict, optional

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

Keyword arguments are the same as ``plot3d_parametric_surface``. Refer to
its documentation for more information.

Examples

Note: for documentation purposes, the following examples uses Matplotlib. However, Matplotlib’s 3D capabilities are rather limited. Consider running these examples with a different backend (hence, modify the rendering_kw and wf_rendering_kw to pass the correct options to the backend).

>>> from sympy import symbols, cos, sin, pi, Ynm, re, lambdify
>>> from spb import plot3d_spherical
>>> theta, phi = symbols('theta phi')

(Source code)

Sphere cap:

>>> plot3d_spherical(1, (theta, 0, 0.7 * pi), (phi, 0, 1.8 * pi))
Plot object containing:
[0]: parametric cartesian surface: (sin(theta)*cos(phi), sin(phi)*sin(theta), cos(theta)) for theta over (0.0, 2.199114857512855) and phi over (0.0, 5.654866776461628)

(Source code, png, hires.png, pdf)

../_images/functions-36.png

Plot real spherical harmonics, highlighting the regions in which the real part is positive and negative, using Plotly:

from sympy import symbols, sin, pi, Ynm, re, lambdify
from spb import plot3d_spherical, PB
theta, phi = symbols('theta phi')
r = re(Ynm(3, 3, theta, phi).expand(func=True).rewrite(sin).expand())
plot3d_spherical(
    abs(r), (theta, 0, pi), (phi, 0, 2 * pi), "radius",
    use_cm=True, n2=200, backend=PB,
    color_func=lambdify([theta, phi], r))

(Source code, png, html, pdf)

Multiple surfaces with wireframe lines, using Plotly. Note that activating the wireframe option might add a considerable overhead during the plot’s creation.

from sympy import symbols, sin, pi
from spb import plot3d_spherical, PB
theta, phi = symbols('theta phi')
r1 = 1
r2 = 1.5 + sin(5 * phi) * sin(10 * theta) / 10
plot3d_spherical(r1, r2, (theta, 0, pi / 2), (phi, 0.35 * pi, 2 * pi),
    wireframe=True, wf_n2=25, backend=PB)

(Source code, png, html, pdf)

Interactive-widget plot of spherical harmonics. Note that the plot’s creation and update might be slow and that it must be m < n at all times. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
import param
n, m = symbols("n, m")
phi, theta = symbols("phi, theta", real=True)
r = abs(re(Ynm(n, m, theta, phi).expand(func=True).rewrite(sin).expand()))
plot3d_spherical(
    r, (theta, 0, pi), (phi, 0, 2*pi),
    params = {
        n: param.Integer(0, label="n"),
        m: param.Integer(0, label="m"),
    },
    backend=KB
 )
spb.functions.plot3d_revolution(curve, range_t, range_phi=None, axis=(0, 0), parallel_axis='z', show_curve=False, curve_kw=None, **kwargs)[source]

Generate a surface of revolution by rotating a curve around an axis of rotation.

Parameters
curveExpr, list/tuple of 2 or 3 elements

The curve to be revolved, which can be either:

  • a symbolic expression

  • a 2-tuple representing a parametric curve in 2D space

  • a 3-tuple representing a parametric curve in 3D space

range_t(symbol, min, max)

A 3-tuple denoting the range of the parameter of the curve.

range_phi(symbol, min, max)

A 3-tuple denoting the range of the azimuthal angle where the curve will be revolved. Default to (phi, 0, 2*pi).

axis(coord1, coord2)

A 2-tuple that specifies the position of the rotation axis. Depending on the value of parallel_axis:

  • “x”: the rotation axis intersects the YZ plane at (coord1, coord2).

  • “y”: the rotation axis intersects the XZ plane at (coord1, coord2).

  • “z”: the rotation axis intersects the XY plane at (coord1, coord2).

Default to (0, 0).

parallel_axisstr

Specify the axis parallel to the axis of rotation. Must be one of the following options: “x”, “y” or “z”. Default to “z”.

show_curvebool

Add the initial curve to the plot. Default to False.

curve_kwdict

A dictionary of options that will be passed to plot3d_parametric_line if show_curve=True in order to customize the appearance of the initial curve. Refer to its documentation for more information.

**kwargs

Keyword arguments are the same as plot3d_parametric_surface. Refer to its documentation for more information.

Examples

Note: for documentation purposes, the following examples uses Matplotlib. However, Matplotlib’s 3D capabilities are rather limited. Consider running these examples with a different backend (hence, modify the curve_kw, rendering_kw and wf_rendering_kw to pass the correct options to the backend).

>>> from sympy import symbols, cos, sin, pi
>>> from spb import plot3d_revolution
>>> t, phi = symbols('t phi')

(Source code)

Revolve a function around the z axis:

>>> plot3d_revolution(
...     cos(t), (t, 0, pi),
...     # use a color map on the surface to indicate the azimuthal angle
...     use_cm=True, color_func=lambda t, phi: phi,
...     rendering_kw={"alpha": 0.6, "cmap": "twilight"},
...     # indicates the azimuthal angle on the colorbar label
...     label=r"$\phi$ [rad]",
...     show_curve=True,
...     # this dictionary will be passes to plot3d_parametric_line in
...     # order to draw the initial curve
...     curve_kw=dict(rendering_kw={"color": "r", "label": "cos(t)"}),
...     # activate the wireframe to visualize the parameterization
...     wireframe=True, wf_n1=15, wf_n2=15,
...     wf_rendering_kw={"lw": 0.5, "alpha": 0.75})

(Source code, png, hires.png, pdf)

../_images/functions-40.png

Revolve the same function around an axis parallel to the x axis, using Plotly:

from sympy import symbols, cos, sin, pi
from spb import plot3d_revolution, PB
t, phi = symbols('t phi')
plot3d_revolution(
    cos(t), (t, 0, pi), parallel_axis="x", axis=(1, 0),
    backend=PB, use_cm=True, color_func=lambda t, phi: phi,
    rendering_kw={"colorscale": "twilight"},
    label="phi [rad]",
    show_curve=True,
    curve_kw=dict(rendering_kw={"line": {"color": "red", "width": 8},
        "name": "cos(t)"}),
    wireframe=True, wf_n1=15, wf_n2=15,
    wf_rendering_kw={"line_width": 1})

(Source code, png, html, pdf)

Revolve a 2D parametric circle around the z axis:

>>> circle = (3 + cos(t), sin(t))
>>> plot3d_revolution(
...     circle, (t, 0, 2 * pi),
...     rendering_kw={"alpha": 0.1},
...     wireframe=True, wf_n1=15, wf_n2=15,
...     wf_rendering_kw={"lw": 0.5, "alpha": 0.75},
...     show_curve=True, zlim=(-2.5, 2.5))

(Source code, png, hires.png, pdf)

../_images/functions-42.png

Revolve a 3D parametric curve around the z axis for a given azimuthal angle, using Plotly:

plot3d_revolution(
    (cos(t), sin(t), t), (t, 0, 2*pi), (phi, 0, pi),
    use_cm=True, color_func=lambda t, phi: t, label="t [rad]",
    show_curve=True, backend=PB, aspect="cube",
    wireframe=True, wf_n1=2, wf_n2=5)

(Source code, png, html, pdf)

Interactive-widget plot of a goblet. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
t, u = symbols("t u")
plot3d_revolution(
    (t, cos(u * t), t**2), (t, 0, 2), axis=(1, 0.2),
    params={u: (2.5, 0, 6)}, n=50, backend=KB,
    wireframe=True, wf_n1=15, wf_n2=15,
    wf_rendering_kw={"width": 0.004},
    show_curve=True, curve_kw={"rendering_kw": {"width": 0.025}})
spb.functions.plot3d_implicit(*args, **kwargs)[source]

Plots an isosurface of a function.

Typical usage examples are in the followings:

  • plot3d_parametric_surface(expr, range_x, range_y, range_z, rendering_kw [optional], **kwargs)

Note that:

  1. it is important to specify the ranges, as they will determine the orientation of the surface.

  2. the number of discretization points is crucial as the algorithm will discretize a volume. A high number of discretization points creates a smoother mesh, at the cost of a much higher memory consumption and slower computation.

  3. To plot f(x, y, z) = c either write expr = f(x, y, z) - c or pass the appropriate keyword to rendering_kw. Read the backends documentation to find out the available options.

  4. Only PlotlyBackend and K3DBackend support 3D implicit plotting.

Parameters
args
expr: Expr

Implicit expression. It can be a:

  • Symbolic expression.

  • Numerical function of three variable, f(x, y, z), supporting vectorization.

range_x: (symbol, min, max)

A 3-tuple denoting the range of the x variable.

range_y: (symbol, min, max)

A 3-tuple denoting the range of the y variable.

range_z: (symbol, min, max)

A 3-tuple denoting the range of the z variable.

rendering_kwdict, optional

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

backendPlot, optional

A subclass of Plot, which will perform the rendering.

n1, n2, n3int, optional

Set the number of discretization points along the x, y and z ranges, respectively. Default value is 60.

nint or three-elements tuple (n1, n2, n3), optional

If an integer is provided, the x, y and z ranges are sampled uniformly at n of points. If a tuple is provided, it overrides n1, n2 and n3.

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 surfaces. 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 expressions.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

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.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

zlabelstr, optional

Label for the z-axis.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart. Note that the function is still being evaluated over the range_x.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart. Note that the function is still being evaluated over the range_y.

zlim(float, float), optional

Denotes the z-axis limits, (min, max), visible in the chart. Note that the function is still being evaluated over the range_z.

Examples

from sympy import symbols
from spb import plot3d_implicit, PB, KB
x, y, z = symbols('x, y, z')
plot3d_implicit(
    x**2 + y**3 - z**2, (x, -2, 2), (y, -2, 2), (z, -2, 2), backend=PB)

(Source code, png, html, pdf)

plot3d_implicit(
    x**4 + y**4 + z**4 - (x**2 + y**2 + z**2 - 0.3),
    (x, -2, 2), (y, -2, 2), (z, -2, 2), backend=PB)

(Source code, png, html, pdf)

Visualize the isocontours from isomin=0 to isomax=2 by providing a rendering_kw dictionary:

plot3d_implicit(
    1/x**2 - 1/y**2 + 1/z**2, (x, -2, 2), (y, -2, 2), (z, -2, 2),
    {
        "isomin": 0, "isomax": 2,
        "colorscale":"aggrnyl", "showscale":True
    },
    backend=PB
)

(Source code, png, html, pdf)

Plotting a numerical function instead of a symbolic expression:

import numpy as np
plot3d_implicit(lambda x, y, z: x**2 + y**2 - z**2,
    ("x", -3, 3), ("y", -3, 3), ("z", 0, 3), backend=PB)

(Source code, png, html, pdf)

spb.functions.plot_contour(*args, **kwargs)[source]

Draws contour plot of a function of two variables.

This function signature is almost identical to plot3d: refer to its documentation for a full list of available argument and keyword arguments.

Parameters
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.

is_filledbool, optional

Choose between filled contours or line contours. Default to True (filled contours).

Examples

>>> from sympy import symbols, cos, exp, sin, pi, Eq, Add
>>> from spb import plot_contour
>>> x, y = symbols('x, y')

(Source code)

Filled contours of a function of two variables.

>>> plot_contour(cos((x**2 + y**2)) * exp(-(x**2 + y**2) / 10),
...      (x, -5, 5), (y, -5, 5))
Plot object containing:
[0]: contour: exp(-x**2/10 - y**2/10)*cos(x**2 + y**2) for x over (-5.0, 5.0) and y over (-5.0, 5.0)

(Source code, png, hires.png, pdf)

../_images/functions-49.png

Line contours of a function of two variables.

>>> expr = 5 * (cos(x) - 0.2 * sin(y))**2 + 5 * (-0.2 * cos(x) + sin(y))**2
>>> plot_contour(expr, (x, 0, 2 * pi), (y, 0, 2 * pi), is_filled=False)
Plot object containing:
[0]: contour: 5*(-0.2*sin(y) + cos(x))**2 + 5*(sin(y) - 0.2*cos(x))**2 for x over (0.0, 6.283185307179586) and y over (0.0, 6.283185307179586)

(Source code, png, hires.png, pdf)

../_images/functions-50.png

Combining together filled and line contours. Use a custom label on the colorbar of the filled contour.

>>> expr = 5 * (cos(x) - 0.2 * sin(y))**2 + 5 * (-0.2 * cos(x) + sin(y))**2
>>> p1 = plot_contour(expr, (x, 0, 2 * pi), (y, 0, 2 * pi), "z",
...      {"cmap": "coolwarm"}, show=False, grid=False)
>>> p2 = plot_contour(expr, (x, 0, 2 * pi), (y, 0, 2 * pi),
...      {"colors": "k", "cmap": None, "linewidths": 0.75},
...      show=False, is_filled=False)
>>> (p1 + p2).show()

(Source code, png, hires.png, pdf)

../_images/functions-51.png

Visually inspect the solutions of a system of 2 non-linear equations. The intersections between the contour lines represent the solutions.

>>> eq1 = Eq((cos(x) - sin(y) / 2)**2 + 3 * (-sin(x) + cos(y) / 2)**2, 2)
>>> eq2 = Eq((cos(x) - 2 * sin(y))**2 - (sin(x) + 2 * cos(y))**2, 3)
>>> plot_contour(eq1.rewrite(Add), eq2.rewrite(Add), {"levels": [0]},
...      (x, 0, 2 * pi), (y, 0, 2 * pi), is_filled=False)

(Source code, png, hires.png, pdf)

../_images/functions-52.png

Interactive-widget plot. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
x, y, a = symbols("x y a")
plot_contour(
    cos(a * x**2 + y**2), (x, -2, 2), (y, -2, 2),
    params={a: (1, 0, 2)}, grid=False)
spb.functions.plot_implicit(*args, **kwargs)[source]

Plot implicit equations / inequalities.

plot_implicit, by default, generates a contour using a mesh grid of fixed number of points. The greater the number of points, the greater the memory used. By setting adaptive=True, interval arithmetic will be used to plot functions. If the expression cannot be plotted using interval arithmetic, it defaults to generating a contour using a mesh grid. With interval arithmetic, the line width can become very small; in those cases, it is better to use the mesh grid approach.

Parameters
args
exprExpr, Relational, BooleanFunction

The equation / inequality that is to be plotted.

rangestuples or Symbol

Two tuple denoting the discretization domain, for example: (x, -10, 10), (y, -10, 10) To get a correct plot, at least the horizontal range must be provided. If no range is given, then the free symbols in the expression will be assigned in the order they are sorted, which could ‘invert’ the axis.

Alternatively, a single Symbol corresponding to the horizontal axis must be provided, which will be internally converted to a range (sym, -10, 10).

rendering_kwdict, optional

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

adaptiveBoolean

The default value is set to False, meaning that the internal algorithm uses a mesh grid approach. In such case, Boolean combinations of expressions cannot be plotted. If set to True, the internal algorithm uses interval arithmetic. It switches to the meshgrid approach if the expression cannot be plotted using interval arithmetic.

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.

backendPlot, optional

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

depthinteger

The depth of recursion for adaptive mesh grid. Default value is 0. Takes value in the range (0, 4). Think of the resulting plot as a picture composed by pixels. By increasing depth we are increasing the number of pixels, thus obtaining a more accurate plot.

n1, n2int

Number of discretization points in the horizontal and vertical directions when adaptive=False. Default to 1000.

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

If an integer is provided, the x and y ranges are sampled uniformly at n of points. If a tuple is provided, it overrides n1 and n2.

showBoolean

Default value is True. If set to False, the plot will not be shown. See Plot for further information.

titlestring

The title for the plot.

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.

xlabelstring

The label for the x-axis

ylabelstring

The label for the y-axis

Examples

Plot expressions:

>>> from sympy import symbols, Eq, And, sin, pi
>>> from spb import plot_implicit
>>> x, y = symbols('x y')

(Source code)

Providing only the symbol for the horizontal axis:

>>> plot_implicit(x - 1, x)

(Source code, png, hires.png, pdf)

../_images/functions-54.png

With the range for both symbols:

>>> plot_implicit(Eq(x**2 + y**2, 3), (x, -3, 3), (y, -3, 3))

(Source code, png, hires.png, pdf)

../_images/functions-55.png

Specify the number of discretization points for the contour algorithm:

>>> plot_implicit(
...     (x**2 + y**2 - 1)**3 - x**2 * y**3,
...     (x, -1.5, 1.5), (y, -1.5, 1.5),
...     n = 500)

(Source code, png, hires.png, pdf)

../_images/functions-56.png

Using adaptive meshing and Boolean expressions:

>>> plot_implicit(
...     Eq(y, sin(x)) & (y > 0),
...     Eq(y, sin(x)) & (y < 0),
...     (x, -2 * pi, 2 * pi), (y, -4, 4),
...     adaptive=True)

(Source code, png, hires.png, pdf)

../_images/functions-57.png

Using adaptive meshing with depth of recursion as argument:

>>> plot_implicit(
...     Eq(x**2 + y**2, 5), (x, -4, 4), (y, -4, 4),
...     adaptive=True, depth=2)

(Source code, png, hires.png, pdf)

../_images/functions-58.png

Plotting regions:

>>> plot_implicit(y > x**2, (x, -5, 5))

(Source code, png, hires.png, pdf)

../_images/functions-59.png
spb.functions.plot_polar(*args, **kwargs)[source]

The following function creates a 2D polar plot.

This function signature is identical to plot: refer to its documentation for a list of available argument and keyword arguments.

Examples

>>> from sympy import symbols, sin, pi
>>> from spb import plot_polar
>>> x = symbols('x')

(Source code)

>>> plot_polar(1 + sin(10 * x) / 10, (x, 0, 2 * pi))

(Source code, png, hires.png, pdf)

../_images/functions-61.png
spb.functions.plot_geometry(*args, **kwargs)[source]

Plot entities from the sympy.geometry module.

Parameters
args
geomGeometryEntity

Represent the geometric entity to be plotted.

labelstr, optional

The name of the geometry entity to be eventually shown on the legend. If not provided, the string representation of geom 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 or fills. Refer to the plotting library (backend) manual for more informations.

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.

backendPlot, optional

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

is_filledboolean

Default to True. Fill the polygon/circle/ellipse.

labelstr or list/tuple, optional

The label to be shown in the legend. If not provided, the string representation of geom will be used. The number of labels must be equal to the number of geometric entities.

paramsdict

A dictionary in which the keys are symbols, enabling two different modes of operation:

  1. If the values are numbers, the dictionary acts like a substitution dictionary for the provided geometric entities.

  2. If the values are tuples representing parameters, the dictionary 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 iplot.

axis_center(float, float), optional

Tuple of two floats denoting the coordinates of the center or {‘center’, ‘auto’}. Only available with MatplotlibBackend.

rendering_kwdict or list of dicts, optional

A dictionary of keywords/values which is passed to the backend’s functions to customize the appearance of lines and/or fills. 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 expressions.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

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.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

zlabelstr, optional

Label for the z-axis.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart.

zlim(float, float), optional

Denotes the z-axis limits, (min, max), visible in the chart.

Examples

>>> from sympy import (symbols, Circle, Ellipse, Polygon,
...      Curve, Segment, Point2D, Point3D, Line3D, Plane,
...      Rational, pi, Point, cos, sin)
>>> from spb import plot_geometry
>>> x, y, z = symbols('x, y, z')

(Source code)

Plot several numeric geometric entitiesy. By default, circles, ellipses and polygons are going to be filled. Plotting Curve objects is the same as plot_parametric.

>>> plot_geometry(
...      Circle(Point(0, 0), 5),
...      Ellipse(Point(-3, 2), hradius=3, eccentricity=Rational(4, 5)),
...      Polygon((4, 0), 4, n=5),
...      Curve((cos(x), sin(x)), (x, 0, 2 * pi)),
...      Segment((-4, -6), (6, 6)),
...      Point2D(0, 0))
Plot object containing:
[0]: geometry entity: Circle(Point2D(0, 0), 5)
[1]: geometry entity: Ellipse(Point2D(-3, 2), 3, 9/5)
[2]: geometry entity: RegularPolygon(Point2D(4, 0), 4, 5, 0)
[3]: parametric cartesian line: (cos(x), sin(x)) for x over (0.0, 6.283185307179586)
[4]: geometry entity: Segment2D(Point2D(-4, -6), Point2D(6, 6))
[5]: geometry entity: Point2D(0, 0)

(Source code, png, hires.png, pdf)

../_images/functions-63.png

Plot several numeric geometric entities defined by numbers only, turn off fill. Every entity is represented as a line.

>>> plot_geometry(
...      Circle(Point(0, 0), 5),
...      Ellipse(Point(-3, 2), hradius=3, eccentricity=Rational(4, 5)),
...      Polygon((4, 0), 4, n=5),
...      Curve((cos(x), sin(x)), (x, 0, 2 * pi)),
...      Segment((-4, -6), (6, 6)),
...      Point2D(0, 0), is_filled=False)
Plot object containing:
[0]: geometry entity: Circle(Point2D(0, 0), 5)
[1]: geometry entity: Ellipse(Point2D(-3, 2), 3, 9/5)
[2]: geometry entity: RegularPolygon(Point2D(4, 0), 4, 5, 0)
[3]: parametric cartesian line: (cos(x), sin(x)) for x over (0.0, 6.283185307179586)
[4]: geometry entity: Segment2D(Point2D(-4, -6), Point2D(6, 6))
[5]: geometry entity: Point2D(0, 0)

(Source code, png, hires.png, pdf)

../_images/functions-64.png

Plot several symbolic geometric entities. We need to pass in the params dictionary, which will be used to substitute symbols before numerical evaluation. Note: here we also set custom labels:

>>> a, b, c, d = symbols("a, b, c, d")
>>> plot_geometry(
...      (Polygon((a, b), c, n=d), "triangle"),
...      (Polygon((a + 2, b + 3), c, n=d + 1), "square"),
...      params = {a: 0, b: 1, c: 2, d: 3})
Plot object containing:
[0]: geometry entity: RegularPolygon(Point2D(a, b), c, d, 0)
[1]: geometry entity: RegularPolygon(Point2D(a + 2, b + 3), c, d + 1, 0)

(Source code, png, hires.png, pdf)

../_images/functions-65.png

Plot 3D geometric entities. Note: when plotting a Plane, we must always provide the x/y/z ranges:

>>> plot_geometry(
...      (Point3D(5, 5, 5), "center"),
...      (Line3D(Point3D(-2, -3, -4), Point3D(2, 3, 4)), "line"),
...      (Plane((0, 0, 0), (1, 1, 1)),
...          (x, -5, 5), (y, -4, 4), (z, -10, 10)))
Plot object containing:
[0]: geometry entity: Point3D(5, 5, 5)
[1]: geometry entity: Line3D(Point3D(-2, -3, -4), Point3D(2, 3, 4))
[2]: plane series over (x, -5, 5), (y, -4, 4), (z, -10, 10)

(Source code, png, hires.png, pdf)

../_images/functions-66.png

Interactive-widget plot. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
import param
a, b, c, d = symbols("a, b, c, d")
plot_geometry(
    (Polygon((a, b), c, n=d), "a"),
    (Polygon((a + 2, b + 3), c, n=d + 1), "b"),
    params = {
        a: (0, -1, 1),
        b: (1, -1, 1),
        c: (2, 1, 2),
        d: param.Integer(3, softbounds=(3, 8), label="n")
    },
    aspect="equal", is_filled=False,
    xlim=(-2.5, 5.5), ylim=(-3, 6.5))
spb.functions.plot_list(*args, **kwargs)[source]

Plots lists of coordinates (ie, lists of numbers).

Typical usage examples are in the followings:

  • Plotting coordinates of a single function.

    plot(x, y, **kwargs)

  • Plotting coordinates of multiple functions adding custom labels.

    plot((x1, y1, label1), (x2, y2, label2), **kwargs)

Parameters
args
xlist or tuple

x-coordinates

ylist or tuple

y-coordinates

labelstr, optional

The label to be shown in the legend.

rendering_kwdict, optional

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

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.

axis_center(float, float), optional

Tuple of two floats denoting the coordinates of the center or {‘center’, ‘auto’}. Only available with MatplotlibBackend.

backendPlot, optional

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

is_pointboolean, optional

Default to False, which will render a line connecting all the points. If True, a scatter plot will be generated.

is_filledboolean, optional

Default to True, which will render empty circular markers. It only works if is_point=True. If False, filled circular markers will be rendered.

labelstr or list/tuple, optional

The label to be shown in the legend. The number of labels must be equal to the number of expressions.

paramsdict

A dictionary mapping symbols to parameters. This keyword argument enables the interactive-widgets plot. Learn more by reading the documentation of iplot.

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. 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 expressions.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

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.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

xscale‘linear’ or ‘log’, optional

Sets the scaling of the x-axis. Default to ‘linear’.

yscale‘linear’ or ‘log’, optional

Sets the scaling of the y-axis. Default to ‘linear’.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart.

Examples

>>> from sympy import symbols, sin, cos
>>> from spb import plot_list
>>> x = symbols('x')

(Source code)

Plot the coordinates of a single function:

>>> xx = [t / 100 * 6 - 3 for t in list(range(101))]
>>> yy = [cos(x).evalf(subs={x: t}) for t in xx]
>>> plot_list(xx, yy)
Plot object containing:
[0]: list plot

(Source code, png, hires.png, pdf)

../_images/functions-68.png

Plot individual points with custom labels:

>>> plot_list(([0], [0], "A"), ([1], [1], "B"), ([2], [0], "C"),
...     is_point=True, is_filled=True)
Plot object containing:
[0]: list plot
[1]: list plot
[2]: list plot

(Source code, png, hires.png, pdf)

../_images/functions-69.png

Scatter plot of the coordinates of multiple functions, with custom rendering keywords:

>>> xx = [t / 70 * 6 - 3 for t in list(range(71))]
>>> yy1 = [cos(x).evalf(subs={x: t}) for t in xx]
>>> yy2 = [sin(x).evalf(subs={x: t}) for t in xx]
>>> plot_list(
...     (xx, yy1, "cos"),
...     (xx, yy2, "sin", {"marker": "*", "markerfacecolor": None}),
...     is_point=True)
Plot object containing:
[0]: list plot
[1]: list plot

(Source code, png, hires.png, pdf)

../_images/functions-70.png

Interactive-widget plot. Refer to iplot documentation to learn more about the params dictionary.

from sympy import *
from spb import *
x, t = symbols("x, t")
params = {t: (0, 0, 2*pi)}
# plot trajectories
p1 = plot_parametric(
    (cos(x), sin(x), (x, 0, 2*pi), {"linestyle": ":"}),
    (cos(2 * x) / 2, sin(2 * x) / 2, (x, 0, pi), {"linestyle": ":"}),
    params=params, use_cm=False, aspect="equal", show=False)
# plot points
p2 = plot_list(
    ([cos(t)], [sin(t)], "A"),
    ([cos(2 * t) / 2], [sin(2 * t) / 2], "B"),
    rendering_kw={"marker": "s", "markerfacecolor": None},
    params=params, is_point=True, show=False)
(p1 + p2).show()
spb.functions.plot_piecewise(*args, **kwargs)[source]

Plots univariate piecewise functions.

Typical usage examples are in the followings:

  • Plotting a single expression with a single range.

    plot_piecewise(expr, range, **kwargs)

  • Plotting a single expression with the default range (-10, 10).

    plot_piecewise(expr, **kwargs)

  • Plotting multiple expressions with a single range.

    plot_piecewise(expr1, expr2, …, range, **kwargs)

  • Plotting multiple expressions with multiple ranges.

    plot_piecewise((expr1, range1), (expr2, range2), …, **kwargs)

  • Plotting multiple expressions with multiple ranges and custom labels.

    plot_piecewise((expr1, range1, label1), (expr2, range2, label2), …, **kwargs)

Parameters
args
exprExpr

Expression representing the function of one variable to be plotted.

range: (symbol, min, max)

A 3-tuple denoting the range of the x variable. Default values: min=-10 and max=10.

labelstr, optional

The label to be shown in the legend. If not provided, the string representation of expr 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. Refer to the plotting library (backend) manual for more informations.

adaptivebool, optional

The default value is set to True, which uses the adaptive algorithm implemented in 5 to create smooth plots. Use adaptive_goal and loss_fn to further customize the output.

Set adaptive to False and specify n if uniform sampling is required.

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 5 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.

axis_center(float, float), optional

Tuple of two floats denoting the coordinates of the center or {‘center’, ‘auto’}. Only available with MatplotlibBackend.

backendPlot, optional

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

detect_polesboolean

Chose whether to detect and correctly plot poles. Defaulto to False. To improve detection, increase the number of discretization points n and/or change the value of eps.

epsfloat

An arbitrary small value used by the detect_poles algorithm. Default value to 0.1. Before changing this value, it is recommended to increase the number of discretization points.

labelstr or list/tuple, optional

The label to be shown in the legend. If not provided, the string representation of expr will be used. If a list/tuple is provided, 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 5 for more information. Specifically, look at adaptive.learner.learner1D to find more loss functions.

nint, optional

Used when the adaptive is set to False. The function is uniformly sampled at n number of points. Default value to 1000. If the adaptive flag is set to True, this parameter will be ignored.

showbool, optional

The default value is set to True. Set show to False and the function will not display the plot. The returned instance of the Plot class can then be used to save or display the plot by calling the save() and show() methods respectively.

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.

titlestr, optional

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

tx, tycallable, optional

Apply a numerical function to the discretized domain in the x and y directions, respectively.

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.

xlabelstr, optional

Label for the x-axis.

ylabelstr, optional

Label for the y-axis.

xscale‘linear’ or ‘log’, optional

Sets the scaling of the x-axis. Default to ‘linear’.

yscale‘linear’ or ‘log’, optional

Sets the scaling of the y-axis. Default to ‘linear’.

xlim(float, float), optional

Denotes the x-axis limits, (min, max), visible in the chart. Note that the function is still being evaluated over the specified range.

ylim(float, float), optional

Denotes the y-axis limits, (min, max), visible in the chart.

References

5(1,2,3)

https://github.com/python-adaptive/adaptive

Examples

>>> from sympy import symbols, sin, cos, pi, Heaviside, Piecewise
>>> from spb import plot_piecewise
>>> x = symbols('x')

(Source code)

Single Plot

>>> plot_piecewise(Heaviside(x, 0).rewrite(Piecewise), (x, -10, 10))
Plot object containing:
[0]: cartesian line: 0 for x over (-10.0, 0.0)
[1]: cartesian line: 1 for x over (1e-06, 10.0)
[2]: list plot
[3]: list plot

(Source code, png, hires.png, pdf)

../_images/functions-72.png

Plot multiple expressions in which the second piecewise expression has a dotted line style.

>>> plot_piecewise(
...   (Heaviside(x, 0).rewrite(Piecewise), (x, -10, 10)),
...   (Piecewise(
...      (sin(x), x < -5),
...      (cos(x), x > 5),
...      (1 / x, True)), (x, -8, 8), {"linestyle": ":"}),
...   ylim=(-2, 2))
Plot object containing:
[0]: cartesian line: 0 for x over (-10.0, 0.0)
[1]: cartesian line: 1 for x over (1e-06, 10.0)
[2]: list plot
[3]: list plot
[4]: cartesian line: sin(x) for x over (-10.0, -5.000001)
[5]: list plot
[6]: cartesian line: cos(x) for x over (5.000001, 10.0)
[7]: list plot
[8]: cartesian line: 1/x for x over (-5.0, 5.0)
[9]: list plot
[10]: list plot

(Source code, png, hires.png, pdf)

../_images/functions-73.png