2D general plotting

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

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

Setting adaptive=True activates the adaptive algorithm implemented in [1] to create smooth plots. Use adaptive_goal and loss_fn to further customize the output.

The default value is False, which uses an uniform sampling strategy, where the number of discretization points is specified by the n keyword argument.

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 or Expr, optional

Define the line color mapping. It can either be:

  • A numerical function of 2 variables, x, y (the points computed by the internal algorithm) supporting vectorization.

  • A symbolic expression having at most as many free symbols as expr.

  • None: the default value (no color mapping).

detect_polesboolean or str, optional

Chose whether to detect and correctly plot poles. There are two algorithms at work:

  1. based on the gradient of the numerical data, it introduces NaN values at locations where the steepness is greater than some threshold. This splits the line into multiple segments. To improve detection, increase the number of discretization points n and/or change the value of eps.

  2. a symbolic approach based on the continuous_domain function from the sympy.calculus.util module, which computes the locations of discontinuities. If any is found, vertical lines will be shown.

Possible options:

  • True: activate poles detection computed with the numerical gradient.

  • False: no poles detection.

  • "symbolic": use both numerical and symbolic algorithms.

Default to False.

epsfloat, optional

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.

force_real_evalboolean, optional

Default to False, with which the numerical evaluation is attempted over a complex domain, which is slower but produces correct results. Set this to True if performance is of paramount importance, but be aware that it might produce wrong results. It only works with adaptive=False.

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.

legendbool, optional

Show/hide the legend. Default to None (the backend determines when it is appropriate to show it).

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. 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 the interactive sub-module.

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.

xlabel, ylabelstr, optional

Labels 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(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.

See also

plot_implicit, plot_polar, plot_parametric, plot_list, plot_contour
plot_geometry, plot_piecewise

References

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))
Plot object containing:
[0]: cartesian line: x**2 for x over (-5.0, 5.0)

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

../_images/2d_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/2d_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/2d_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,
...     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/2d_functions-5.png

Using an adaptive algorithm, detect and plot vertical lines at singularities. Also, 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=True, adaptive_goal=0.001,
...      detect_poles="symbolic", tx=np.rad2deg, ylim=(-7, 7),
...      xlabel="x [deg]", grid=False)
Plot object containing:
[0]: cartesian line: tan(x) for x over (-4.71238898038469, 4.71238898038469)

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

../_images/2d_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/2d_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/2d_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/2d_functions-9.png

Interactive-widget plot of an oscillator. Refer to the interactive sub-module documentation to learn more about the params dictionary. This plot illustrates:

  • plotting multiple expressions, each one with its own label and rendering options.

  • the use of prange (parametric plotting range).

  • the use of the params dictionary to specify sliders in their basic form: (default, min, max).

from sympy import *
from spb import *
x, a, b, c, n = symbols("x, a, b, c, n")
plot(
    (cos(a * x + b) * exp(-c * x), "oscillator"),
    (exp(-c * x), "upper limit", {"linestyle": ":"}),
    (-exp(-c * x), "lower limit", {"linestyle": ":"}),
    prange(x, 0, n * pi),
    params={
        a: (1, 0, 10),     # frequency
        b: (0, 0, 2 * pi), # phase
        c: (0.25, 0, 1),   # damping
        n: (2, 0, 4)       # multiple of pi
    },
    ylim=(-1.25, 1.25), use_latex=False
)

(Source code, small.png)

../_images/2d_functions-10.small.png
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).

labelstr, optional

The label to be shown when multiple expressions are plotted. 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 contours. Refer to the plotting library (backend) manual for more informations.

adaptivebool, optional

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. If the expression cannot be plotted with interval arithmetic, it switches to the meshgrid approach.

border_colorstr or bool, optional

If given, a limiting border will be added when plotting inequalities (<, <=, >, >=).

colorstr, optional

Specify the color of lines/regions. Default to None (automatic coloring by the backend).

aspect(float, float) or str, optional

Set the aspect ratio of the plot. Possible values are "auto" or "equals". Default to "auto".

depthinteger

The depth of recursion for adaptive 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.

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.

legendbool, optional

Show/hide the legend. Default to None (the backend determines when it is appropriate to show it).

rendering_kwdict or list of dicts, optional

A dictionary of keywords/values which is passed to the backend’s function to customize the appearance. If the adaptive algorithm is used, then matplotlib’s fill command will be executed. If adaptive=False, then matplotlib’s contour or contourf commands will be executed. If a list of dictionaries is provided, the number of dictionaries must be equal to the number of expressions.

n1, n2int

Number of discretization points in the horizontal and vertical directions when adaptive=False. Default 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. Learn more by reading the documentation of the interactive sub-module.

showbool

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

show_in_legendbool

If True, add a legend entry for the expression being plotted. This option is useful to hide a particular expression when combining together multiple plots. Default to True.

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.

xlabel, ylabelstring

The labels for the x-axis or y-axis, respectively.

See also

plot, plot_polar, plot_parametric, plot_list, plot_contour
plot_geometry, plot_piecewise

Examples

Plot expressions:

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

(Source code)

Providing only the symbol for the horizontal axis:

>>> p = plot_implicit(x - 1, x)

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

../_images/2d_functions-12.png

Specify both ranges, set the number of discretization points and plot a region:

>>> plot_implicit(y > x**2, (x, -5, 5), (y, -10, 10), n=150, grid=False)
Plot object containing:
[0]: Implicit expression: y > x**2 for x over (-5.0, 5.0) and y over (-10.0, 10.0)

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

../_images/2d_functions-13.png

Plot a region using a custom color, highlights the limiting border and customize its appearance. In this particular case, the content of rendering_kw will be sent to matplotlib’s contour of contourf commands.

>>> expr = 4 * (cos(x) - sin(y) / 5)**2 + 4 * (-cos(x) / 5 + sin(y))**2
>>> plot_implicit(expr <= pi, (x, -pi, pi), (y, -pi, pi),
...     grid=False, color="gold", border_color="k",
...     rendering_kw={"linestyles": "-.", "linewidths": 1})
Plot object containing:
[0]: Implicit expression: 4*(-sin(y)/5 + cos(x))**2 + 4*(sin(y) - cos(x)/5)**2 <= pi for x over (-3.141592653589793, 3.141592653589793) and y over (-3.141592653589793, 3.141592653589793)
[1]: Implicit expression: Eq(-4*(-sin(y)/5 + cos(x))**2 - 4*(sin(y) - cos(x)/5)**2 + pi, 0) for x over (-3.141592653589793, 3.141592653589793) and y over (-3.141592653589793, 3.141592653589793)

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

../_images/2d_functions-14.png

Boolean expressions will be plotted with the adaptive algorithm. Note the thin width of lines:

>>> plot_implicit(
...     Eq(y, sin(x)) & (y > 0),
...     Eq(y, sin(x)) & (y < 0),
...     (x, -2 * pi, 2 * pi), (y, -4, 4))
Plot object containing:
[0]: Implicit expression: (y > 0) & Eq(y, sin(x)) for x over (-6.283185307179586, 6.283185307179586) and y over (-4.0, 4.0)
[1]: Implicit expression: (y < 0) & Eq(y, sin(x)) for x over (-6.283185307179586, 6.283185307179586) and y over (-4.0, 4.0)

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

../_images/2d_functions-15.png

Plotting multiple implicit expressions and setting labels:

>>> V, t, b, L = symbols("V, t, b, L")
>>> L_array = [5, 10, 15, 20, 25]
>>> b_val = 0.0032
>>> expr = b * V * 0.277 * t - b * L - log(1 + b * V * 0.277 * t)
>>> expr_list = [expr.subs({b: b_val, L: L_val}) for L_val in L_array]
>>> labels = ["L = %s" % L_val for L_val in L_array]
>>> plot_implicit(*expr_list, (t, 0, 3), (V, 0, 1000), label=labels)
Plot object containing:
[0]: Implicit expression: Eq(0.0008864*V*t - log(0.0008864*V*t + 1) - 0.016, 0) for t over (0.0, 3.0) and V over (0.0, 1000.0)
[1]: Implicit expression: Eq(0.0008864*V*t - log(0.0008864*V*t + 1) - 0.032, 0) for t over (0.0, 3.0) and V over (0.0, 1000.0)
[2]: Implicit expression: Eq(0.0008864*V*t - log(0.0008864*V*t + 1) - 0.048, 0) for t over (0.0, 3.0) and V over (0.0, 1000.0)
[3]: Implicit expression: Eq(0.0008864*V*t - log(0.0008864*V*t + 1) - 0.064, 0) for t over (0.0, 3.0) and V over (0.0, 1000.0)
[4]: Implicit expression: Eq(0.0008864*V*t - log(0.0008864*V*t + 1) - 0.08, 0) for t over (0.0, 3.0) and V over (0.0, 1000.0)

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

../_images/2d_functions-16.png

Comparison of similar expressions plotted with different algorithms. Note:

  1. Adaptive algorithm (adaptive=True) can be used with any expression, but it usually creates lines with variable thickness. The depth keyword argument can be used to improve the accuracy, but reduces line thickness even further.

  2. Mesh grid algorithm (adaptive=False) creates lines with constant thickness.

>>> expr1 = Eq(x * y - 20, 15 * y)
>>> expr2 = Eq((x - 3) * y - 20, 15 * y)
>>> expr3 = Eq((x - 6) * y - 20, 15 * y)
>>> ranges = (x, 15, 30), (y, 0, 50)
>>> p1 = plot_implicit(expr1, *ranges, adaptive=True, depth=0,
...     label="adaptive=True, depth=0", grid=False, show=False)
>>> p2 = plot_implicit(expr2, *ranges, adaptive=True, depth=1,
...     label="adaptive=True, depth=1", grid=False, show=False)
>>> p3 = plot_implicit(expr3, *ranges, adaptive=False,
...     label="adaptive=False", grid=False, show=False)
>>> (p1 + p2 + p3).show()

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

../_images/2d_functions-17.png

If the expression is plotted with the adaptive algorithm and it produces “low-quality” results, maybe it’s possible to rewrite it in order to use the mesh grid approach (contours). For example:

>>> from spb import plotgrid
>>> expr = Ne(x*y, 1)
>>> p1 = plot_implicit(
...     expr, (x, -10, 10), (y, -10, 10),
...     grid=False, aspect="equal", show=False,
...     title="$%s$ : First approach" % latex(expr))
>>> # plot the entire visible region
>>> p2 = plot_implicit(
...     x < 20, (x, -10, 10), (y, -10, 10),
...     show=False, grid=False, aspect="equal",
...     title="$%s$ : Second approach" % latex(expr))
>>> # plot the excluded contour
>>> p3 = plot_implicit(
...     Eq(*expr.args), (x, -10, 10), (y, -10, 10),
...     color="w", show_in_legend=False, show=False)
>>> plotgrid(p1, (p2 + p3), nc=2)

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

../_images/2d_functions-18.png

Interactive-widget implicit plot. Refer to the interactive sub-module documentation to learn more about the params dictionary. This plot illustrates:

  • the use of prange (parametric plotting range).

  • the use of the params dictionary to specify sliders in their basic form: (default, min, max).

from sympy import *
from spb import *
x, y, a, b, c, d, e = symbols("x, y, a, b, c, d, e")
expr = Eq(a * x**2 - b * x + c, d * y + y**2)
plot_implicit(expr, (x, -2, 2), prange(y, -e, e),
    params={
        a: (10, -15, 15),
        b: (7, -15, 15),
        c: (3, -15, 15),
        d: (2, -15, 15),
        e: (10, 1, 15),
    }, n=150, use_latex=False, ylim=(-10, 10))

(Source code, small.png)

../_images/2d_functions-19.small.png
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

Setting adaptive=True activates the adaptive algorithm implemented in [2] to create smooth plots. Use adaptive_goal and loss_fn to further customize the output.

The default value is False, which uses an uniform sampling strategy, where the number of discretization points is specified by the n keyword argument.

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.

colorbarboolean, optional

Show/hide the colorbar. Default to True (colorbar is visible). Only works when use_cm=True.

color_funccallable, optional

Define the line color mapping when use_cm=True. It can either be:

  • A numerical function supporting vectorization. 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).

  • A symbolic expression having at most as many free symbols as expr_x or expr_y.

  • None: the default value (color mapping applied to the parameter).

force_real_evalboolean, optional

Default to False, with which the numerical evaluation is attempted over a complex domain, which is slower but produces correct results. Set this to True if performance is of paramount importance, but be aware that it might produce wrong results. It only works with adaptive=False.

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.

legendbool, optional

Show/hide the legend. Default to None (the backend determines when it is appropriate to show it). Only works when use_cm=False.

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=False. The function is uniformly sampled at n number of points. Default value to 1000. If the adaptive=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 the interactive sub-module.

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.

xlabel, ylabelstr, optional

Labels 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 limits or y-axis limits, respectively, (min, max), visible in the chart.

See also

plot, plot_implicit, plot_polar, plot_list, plot_contour
plot_geometry, plot_piecewise

References

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/2d_functions-21.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/2d_functions-22.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*v), 5*sin(4*v)) for v over (0.0, 3.141592653589793)

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

../_images/2d_functions-23.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)
>>> p = plot_parametric(fx, fy, ("t", 0, 12 * pi), title="Butterfly Curve",
...     use_cm=False, n=2000)

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

../_images/2d_functions-24.png

Interactive-widget plot. Refer to the interactive sub-module documentation to learn more about the params dictionary. This plot illustrates:

  • the use of prange (parametric plotting range).

  • the use of the params dictionary to specify sliders in their basic form: (default, min, max).

from sympy import *
from spb import *
x, a, s, e = symbols("x a s, e")
plot_parametric(
    cos(a * x), sin(x), prange(x, s*pi, e*pi),
    params={
        a: (0.5, 0, 2),
        s: (0, 0, 2),
        e: (2, 0, 2),
    },
    aspect="equal", use_latex=False,
    xlim=(-1.25, 1.25), ylim=(-1.25, 1.25)
)

(Source code, small.png)

../_images/2d_functions-25.small.png
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

The functions are uniformly sampled at n number of points. Default value to 1000.

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")
>>> p = 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/2d_functions-27.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
>>> p = 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/2d_functions-28.png
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.

clabelsbool, optional

Visualize labels of contour lines. Only works when is_filled=False. Default to True. Note that some backend might not implement this feature.

is_filledbool, optional

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

polar_axisboolean, optional

If True, attempt to create a plot with polar axis. Default to False, which creates a plot with cartesian axis.

See also

plot, plot_implicit, plot_polar, plot_parametric, plot_list, plot3d
plot_geometry, plot_piecewise

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/2d_functions-30.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/2d_functions-31.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/2d_functions-32.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, clabels=False)
Plot object containing:
[0]: contour: 3*(-sin(x) + cos(y)/2)**2 + (-sin(y)/2 + cos(x))**2 - 2 for x over (0.0, 6.283185307179586) and y over (0.0, 6.283185307179586)
[1]: contour: -(sin(x) + 2*cos(y))**2 + (-2*sin(y) + cos(x))**2 - 3 for x over (0.0, 6.283185307179586) and y over (0.0, 6.283185307179586)

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

../_images/2d_functions-33.png

Contour plot with polar axis:

>>> r, theta = symbols("r, theta")
>>> plot_contour(sin(2 * r) * cos(theta), (theta, 0, 2*pi), (r, 0, 7),
...     {"levels": 100}, polar_axis=True, aspect="equal")
Plot object containing:
[0]: contour: sin(2*r)*cos(theta) for theta over (0.0, 6.283185307179586) and r over (0.0, 7.0)

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

../_images/2d_functions-34.png

Interactive-widget plot. Refer to the interactive sub-module documentation to learn more about the params dictionary. This plot illustrates:

  • the use of prange (parametric plotting range).

  • the use of the params dictionary to specify sliders in their basic form: (default, min, max).

from sympy import *
from spb import *
x, y, a, b, xp, yp = symbols("x y a b x_p y_p")
expr = (cos(x) + a * sin(x) * sin(y) - b * sin(x) * cos(y))**2
plot_contour(expr, prange(x, 0, xp*pi), prange(y, 0, yp * pi),
    params={a: (1, 0, 2), b: (1, 0, 2), xp: (1, 0, 2), yp: (2, 0, 2)},
    grid=False, use_latex=False)

(Source code, small.png)

../_images/2d_functions-35.small.png
spb.functions.plot_polar(*args, **kwargs)[source]

The following function creates a 2D polar plot.

By default, it uses an equal aspect ratio and doesn’t apply a colormap.

This function is going to call plot_parametric: refer to its documentation for the full list of keyword arguments.

Parameters:
polar_axisboolean, optional

If True, attempt to create a plot with polar axis. Default to False, which creates a plot with cartesian axis.

See also

plot, plot_implicit, plot_parametric, plot_list, plot_contour
plot_geometry, plot_piecewise

Examples

>>> from sympy import symbols, sin, cos, exp, pi
>>> from spb import plot_polar
>>> theta = symbols('theta')

(Source code)

Plot with cartesian axis:

>>> plot_polar(3 * sin(2 * theta), (theta, 0, 2*pi))
Plot object containing:
[0]: parametric cartesian line: (3*sin(2*theta)*cos(theta), 3*sin(theta)*sin(2*theta)) for theta over (0.0, 6.283185307179586)

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

../_images/2d_functions-37.png

Plot with polar axis:

>>> plot_polar(
...     exp(sin(theta)) - 2 * cos(4 * theta), (theta, 0, 2 * pi),
...     polar_axis=True)
Plot object containing:
[0]: parametric cartesian line: ((exp(sin(theta)) - 2*cos(4*theta))*cos(theta), (exp(sin(theta)) - 2*cos(4*theta))*sin(theta)) for theta over (0.0, 6.283185307179586)

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

../_images/2d_functions-38.png

Interactive-widget plot of Guilloché Pattern. Refer to the interactive sub-module documentation to learn more about the params dictionary. This plot illustrates:

  • the use of prange (parametric plotting range).

  • the use of the params dictionary to specify the widgets to be created by Holoviz’s Panel.

from sympy import *
from spb import *
import param
a, b, c, d, e, f, theta, tp = symbols("a:f theta tp")
def func(n):
    t1 = (c + sin(a * theta + d))
    t2 = ((b + sin(b * theta + e)) - (c + sin(a * theta + d)))
    t3 = (f + sin(a * theta + n / pi))
    return t1 + t2 * t3 / 2
exprs = [func(n) for n in range(20)]
plot_polar(
    *exprs, prange(theta, 0, tp*pi),
    {"line_color": "black", "line_width": 0.5},
    params={
        a: param.Integer(6, label="a"),
        b: param.Integer(12, label="b"),
        c: param.Integer(18, label="c"),
        d: (4.7, 0, 2*pi),
        e: (1.8, 0, 2*pi),
        f: (3, 0, 5),
        tp: (2, 0, 2)
    },
    layout = "sbl",
    ncols = 1,
    title="Guilloché Pattern Explorer",
    backend=BB,
    legend=False,
    use_latex=False,
    servable=True,
    imodule="panel"
)

(Source code, small.png)

../_images/2d_functions-39.small.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.

legendbool, optional

Show/hide the legend. Default to None (the backend determines when it is appropriate to show it).

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 the interactive sub-module.

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.

xlabel, ylabel, zlabelstr, optional

Labels for the x-axis, y-axis or z-axis, respectively.

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

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

See also

plot, plot_implicit, plot_polar, plot_parametric, plot_list
plot_contour, plot_piecewise

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 a single geometry, customizing its color:

>>> plot_geometry(
...     Ellipse(Point(-3, 2), hradius=3, eccentricity=Rational(4, 5)),
...     {"color": "tab:orange"}, grid=False)
Plot object containing:
[0]: geometry entity: Ellipse(Point2D(-3, 2), 3, 9/5)

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

../_images/2d_functions-41.png

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/2d_functions-42.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/2d_functions-43.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]: interactive geometry entity: RegularPolygon(Point2D(a, b), c, d, 0) and parameters (a, b, c, d)
[1]: interactive geometry entity: RegularPolygon(Point2D(a + 2, b + 3), c, d + 1, 0) and parameters (a, b, c, d)

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

../_images/2d_functions-44.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: Plane(Point3D(0, 0, 0), (1, 1, 1)) over (x, -5, 5), (y, -4, 4), (z, -10, 10)

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

../_images/2d_functions-45.png

Interactive-widget plot. Refer to the interactive sub-module 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, use_latex=False,
    xlim=(-2.5, 5.5), ylim=(-3, 6.5), imodule="panel")

(Source code, small.png)

../_images/2d_functions-46.small.png
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_list(x, y, **kwargs)

  • Plotting coordinates of multiple functions adding custom labels.

    plot_list((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 False, which will render empty circular markers. It only works if is_point=True. If True, 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.

legendbool, optional

Show/hide the legend. Default to None (the backend determines when it is appropriate to show it).

paramsdict

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

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.

xlabel, ylabelstr, optional

Labels 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 limits or y-axis limits, respectively, (min, max), visible in the chart.

See also

plot, plot_implicit, plot_polar, plot_parametric, plot_contour
plot_geometry, plot_piecewise, plot3d_list

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]: 2D list plot

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

../_images/2d_functions-48.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]: 2D list plot
[1]: 2D list plot
[2]: 2D list plot

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

../_images/2d_functions-49.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]: 2D list plot
[1]: 2D list plot

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

../_images/2d_functions-50.png

Interactive-widget plot. Refer to the interactive sub-module 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": ":"}),
    use_cm=False, aspect="equal", show=False, use_latex=False,
    params=params, imodule="panel")
# 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()

(Source code, small.png)

../_images/2d_functions-51.small.png
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

Setting adaptive=True activates the adaptive algorithm implemented in [3] to create smooth plots. Use adaptive_goal and loss_fn to further customize the output.

The default value is False, which uses an uniform sampling strategy, where the number of discretization points is specified by the n keyword argument.

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.

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 or str, optional

Chose whether to detect and correctly plot poles. There are two algorithms at work:

  1. based on the gradient of the numerical data, it introduces NaN values at locations where the steepness is greater than some threshold. This splits the line into multiple segments. To improve detection, increase the number of discretization points n and/or change the value of eps.

  2. a symbolic approach based on the continuous_domain function from the sympy.calculus.util module, which computes the locations of discontinuities. If any is found, vertical lines will be shown.

Possible options:

  • True: activate poles detection computed with the numerical gradient.

  • False: no poles detection.

  • "symbolic": use both numerical and symbolic algorithms.

Default to False.

dotsboolean

Wheter to show circular markers at the endpoints. Default to True.

epsfloat, optional

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.

force_real_evalboolean, optional

Default to False, with which the numerical evaluation is attempted over a complex domain, which is slower but produces correct results. Set this to True if performance is of paramount importance, but be aware that it might produce wrong results. It only works with adaptive=False.

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 [3] 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.

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.

xlabel, ylabelstr, optional

Labels 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(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.

See also

plot, plot_implicit, plot_polar, plot_parametric, plot_list
plot_contour, plot_geometry

References

Examples

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

(Source code)

Single Plot

>>> f = Piecewise((x**2, x < 2), (5, Eq(x, 2)), (10 - x, True))
>>> plot_piecewise(f, (x, -2, 5))
Plot object containing:
[0]: cartesian line: x**2 for x over (-2.0, 1.999999)
[1]: 2D list plot
[2]: cartesian line: 10 - x for x over (2.000001, 5.0)
[3]: 2D list plot
[4]: 2D list plot

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

../_images/2d_functions-53.png

Single plot without dots (circular markers):

>>> plot_piecewise(Heaviside(x, 0).rewrite(Piecewise),
...     (x, -10, 10), dots=False)
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)

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

../_images/2d_functions-54.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), detect_poles=True)
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]: 2D list plot
[3]: 2D list plot
[4]: cartesian line: sin(x) for x over (-8.0, -5.000001)
[5]: 2D list plot
[6]: cartesian line: cos(x) for x over (5.000001, 8.0)
[7]: 2D list plot
[8]: cartesian line: 1/x for x over (-5.0, 5.0)
[9]: 2D list plot
[10]: 2D list plot

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

../_images/2d_functions-55.png