Vectors
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,
or widgets from the panel
module, 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.graphics.vectors.arrow_2d(start, direction, label=None, rendering_kw=None, show_in_legend=True, **kwargs)[source]
Draw an arrow in a 2D space.
- Parameters:
- start(x, y)
Coordinates of the start position.
- direction(u, v)
Componenents of the direction vector.
- 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.
- 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.
- Returns:
- A list containing one instance of
Arrow2DSeries
.
- A list containing one instance of
See also
Examples
>>> from spb import * >>> graphics( ... arrow_2d((0, 0), (1, 1)), ... arrow_2d((0, 0), (-1, 1)), ... grid=False, aspect="equal" ... ) Plot object containing: [0]: 2D arrow from (0.0, 0.0) to (1.0, 1.0) [1]: 2D arrow from (0.0, 0.0) to (-1.0, 1.0)
(
Source code
,png
)Interactive-widget plot of arrows. Refer to the interactive sub-module documentation to learn more about the
params
dictionary.from sympy import * from spb import * r, theta = symbols("r, theta") params = { r: (4, 0, 5), theta: (pi/3, 0, 2*pi), } graphics( arrow_2d( (0, 0), (5, 0), show_in_legend=False, rendering_kw={"color": "k"}), arrow_2d( (0, 0), (0, 5), show_in_legend=False, rendering_kw={"color": "k"}), arrow_2d( (0, 0), (r * cos(theta), r * sin(theta)), params=params), arrow_2d( (0, 0), (r * cos(theta + pi/2), r * sin(theta + pi/2)), params=params), xlim=(-6, 6), ylim=(-6, 6), aspect="equal", grid=False )
- spb.graphics.vectors.arrow_3d(start, direction, label=None, rendering_kw=None, show_in_legend=True, **kwargs)[source]
Draw an arrow in a 2D space.
- Parameters:
- start(x, y, z)
Coordinates of the start position.
- direction(u, v, w)
Componenents of the direction vector.
- 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.
- 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.
- Returns:
- A list containing one instance of
Arrow3DSeries
.
- A list containing one instance of
See also
Examples
>>> from spb import * >>> graphics( ... arrow_3d((0, 0, 0), (1, 0, 0)), ... arrow_3d((0, 0, 0), (0, 1, 0)), ... arrow_3d((0, 0, 0), (0, 0, 1), show_in_legend=False, ... rendering_kw={ ... "mutation_scale": 20, ... "arrowstyle": "-|>", ... "linestyle": 'dashed', ... }), ... xlabel="x", ylabel="y", zlabel="z") Plot object containing: [0]: 3D arrow from (0.0, 0.0, 0.0) to (1.0, 0.0, 0.0) [1]: 3D arrow from (0.0, 0.0, 0.0) to (0.0, 1.0, 0.0) [2]: 3D arrow from (0.0, 0.0, 0.0) to (0.0, 0.0, 1.0)
(
Source code
,png
)Interactive-widget plot of arrows. Refer to the interactive sub-module documentation to learn more about the
params
dictionary.from sympy import * from spb import * phi, theta = symbols("phi, theta") r = 0.75 params = { phi: (-pi/2, -pi, pi), theta: (2*pi/3, -pi, pi), } graphics( arrow_3d((0, 0, 0), (1, 0, 0), rendering_kw={"color": "k"}, show_in_legend=False), arrow_3d((0, 0, 0), (0, 1, 0), rendering_kw={"color": "k"}, show_in_legend=False), arrow_3d((0, 0, 0), (0, 0, 1), rendering_kw={"color": "k"}, show_in_legend=False), arrow_3d( (0, 0, 0), (r*sin(theta)*cos(phi), r*sin(theta)*sin(phi), r*cos(theta)), params=params), xlabel="x", ylabel="y", zlabel="z", xlim=(-1.5, 1.5), ylim=(-1.5, 1.5), zlim=(-1.5, 1.5), aspect="equal" )
- spb.graphics.vectors.vector_field_2d(expr1, expr2=None, range1=None, range2=None, label=None, quiver_kw=None, stream_kw=None, contour_kw=None, **kwargs)[source]
Plot a 2D vector field.
- Parameters:
- expr1, expr2Vector, Expr or callable
The components of the vector field. It can be a:
A vector from the sympy.vector module or from the sympy.physics.mechanics module. In this case, only
expr1
is set.Two symbolic expressions, one for each component.
Two numerical functions of 2 variables.
- range1, range23-element tuples
Denotes the range of the variables. For example
(x, -5, 5)
.- labelstr, optional
The name of the vector field to be eventually shown on the legend or colorbar. If none is provided, the string representation of the vector will be used.
- colorbarboolean, optional
Show/hide the colorbar. Default to True (colorbar is visible).
- color_funccallable, optional
Define the quiver/streamlines color mapping when
use_cm=True
. It can either be:A numerical function supporting vectorization. The arity must be:
f(x, y, u, v)
. Further,scalar=False
must be set in order to hide the contour plot so that a colormap is applied to quivers/streamlines.A symbolic expression having at most as many free symbols as
expr1/expr2
. This only works for quivers plot.None: the default value, which will map colors according to the magnitude of the vector field.
- contour_kwdict, optional
A dictionary of keywords/values which is passed to the backend contour function to customize the appearance. Refer to the plotting library (backend) manual for more informations.
- n, n1, n2int, optional
Number of discretization points for the quivers or streamlines in the x/y-direction, respectively. Default to 25.
n
is a shortcut to set the same number of discretization points on both directions.- ncint, optional
Number of discretization points for the scalar contour plot. Default to 100.
- normalizebool, optional
Default to False. If True, the vector field will be normalized, resulting in quivers having the same length. If
use_cm=True
, the backend will color the quivers by the (pre-normalized) vector field’s magnitude. Note: only quivers will be affected by this option.- paramsdict, optional
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.
- quiver_kwdict, optional
A dictionary of keywords/values which is passed to the backend quivers- plotting function to customize the appearance. Refer to the plotting library (backend) manual for more informations.
- scalarboolean, Expr, None or list/tuple of 2 elements, optional
Represents the scalar field to be plotted in the background of a 2D vector field plot. It can be:
True: plot the magnitude of the vector field. Only works when a single vector field is plotted.
False/None: do not plot any scalar field.
Expr: a symbolic expression representing the scalar field.
a numerical function of 2 variables supporting vectorization.
list/tuple: [scalar_expr, label], where the label will be shown on the colorbar. scalar_expr can be a symbolic expression or a numerical function of 2 variables supporting vectorization.
Default to True.
- 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.
- streamlinesboolean, optional
Whether to plot the vector field using streamlines (True) or quivers (False). Default to False.
- stream_kwdict, optional
A dictionary of keywords/values which is passed to the backend streamlines-plotting function to customize the appearance. Refer to the Notes section to learn more.
- Returns:
- serieslist
A list containing one instance of
ContourSeries
(ifscalar
is set) and one instance ofVector2DSeries
.
See also
Examples
>>> from sympy import symbols, sin, cos, Plane, Matrix, sqrt, latex >>> from spb import * >>> x, y, z = symbols('x, y, z')
Quivers plot of a 2D vector field with a contour plot in background representing the vector’s magnitude (a scalar field).
>>> graphics( ... vector_field_2d(sin(x - y), cos(x + y), (x, -3, 3), (y, -3, 3), ... quiver_kw=dict(color="black", scale=30, headwidth=5), ... contour_kw={"cmap": "Blues_r", "levels": 15}), ... grid=False, xlabel="x", ylabel="y") Plot object containing: [0]: contour: sqrt(sin(x - y)**2 + cos(x + y)**2) for x over (-3.0, 3.0) and y over (-3.0, 3.0) [1]: 2D vector series: [sin(x - y), cos(x + y)] over (x, -3.0, 3.0), (y, -3.0, 3.0)
(
Source code
,png
)Quivers plot of a 2D vector field with no background scalar field, a custom label and normalized quiver lengths:
>>> graphics( ... vector_field_2d(sin(x - y), cos(x + y), (x, -3, 3), (y, -3, 3), ... label="Magnitude of $%s$" % latex([-sin(y), cos(x)]), ... scalar=False, normalize=True, ... quiver_kw={ ... "scale": 35, "headwidth": 4, "cmap": "gray", ... "clim": [0, 1.6]}), ... grid=False, xlabel="x", ylabel="y") Plot object containing: [0]: 2D vector series: [sin(x - y), cos(x + y)] over (x, -3.0, 3.0), (y, -3.0, 3.0)
(
Source code
,png
)Streamlines plot of a 2D vector field with no background scalar field, and a custom label:
>>> graphics( ... vector_field_2d(sin(x - y), cos(x + y), (x, -3, 3), (y, -3, 3), ... streamlines=True, scalar=None, ... stream_kw={"density": 1.5}, ... label="Magnitude of %s" % str([sin(x - y), cos(x + y)])), ... xlabel="x", ylabel="y", grid=False) Plot object containing: [0]: 2D vector series: [sin(x - y), cos(x + y)] over (x, -3.0, 3.0), (y, -3.0, 3.0)
(
Source code
,png
)Plot multiple 2D vectors fields, setting a background scalar field to be the magnitude of the first vector. Also, apply custom rendering options to all data series.
>>> scalar_expr = sqrt((-sin(y))**2 + cos(x)**2) >>> graphics( ... vector_field_2d(-sin(y), cos(x), (x, -5, 5), (y, -3, 3), n=20, ... scalar=[scalar_expr, "$%s$" % latex(scalar_expr)], ... contour_kw={"cmap": "summer"}, ... quiver_kw={"color": "k"}), ... vector_field_2d(2 * y, x, (x, -5, 5), (y, -3, 3), n=20, ... scalar=False, quiver_kw={"color": "r"}, use_cm=False), ... aspect="equal", grid=False, xlabel="x", ylabel="y") Plot object containing: [0]: contour: sqrt(sin(y)**2 + cos(x)**2) for x over (-5.0, 5.0) and y over (-3.0, 3.0) [1]: 2D vector series: [-sin(y), cos(x)] over (x, -5.0, 5.0), (y, -3.0, 3.0) [2]: 2D vector series: [2*y, x] over (x, -5.0, 5.0), (y, -3.0, 3.0)
(
Source code
,png
)Plotting a the streamlines of a 2D vector field defined with numerical functions instead of symbolic expressions:
>>> import numpy as np >>> f = lambda x, y: np.sin(2 * x + 2 * y) >>> fx = lambda x, y: np.cos(f(x, y)) >>> fy = lambda x, y: np.sin(f(x, y)) >>> graphics( ... vector_field_2d(fx, fy, ("x", -1, 1), ("y", -1, 1), ... streamlines=True, scalar=False, use_cm=False), ... aspect="equal", xlabel="x", ylabel="y", grid=False ... )
(
Source code
,png
)Interactive-widget 2D vector plot. Refer to the interactive sub-module documentation to learn more about the
params
dictionary. This plot illustrates:customizing the appearance of quivers and countour.
the use of
prange
(parametric plotting range).the use of the
params
dictionary to specify sliders in their basic form: (default, min, max).the use of
panel.widgets.slider.RangeSlider
, which is a 2-values widget.
from sympy import * from spb import * import panel as pn x, y, a, b, c, d, e = symbols("x, y, a, b, c, d, e") v = [-sin(a * y), cos(b * x)] graphics( vector_field_2d(-sin(a * y), cos(b * x), prange(x, -3*c, 3*c), prange(y, d, e), params={ a: (1, -2, 2), b: (1, -2, 2), c: (1, 0, 2), (d, e): pn.widgets.RangeSlider( value=(-3, 3), start=-9, end=9, step=0.1) }, quiver_kw=dict(color="black", scale=30, headwidth=5), contour_kw={"cmap": "Blues_r", "levels": 15} ), grid=False, xlabel="x", ylabel="y")
- spb.graphics.vectors.vector_field_3d(expr1, expr2=None, expr3=None, range1=None, range2=None, range3=None, label=None, quiver_kw=None, stream_kw=None, **kwargs)[source]
Plot a 3D vector field.
- Parameters:
- expr1, expr2, expr3Vector, Expr or callable
The components of the vector field. It can be a:
A vector from the sympy.vector module or from the sympy.physics.mechanics module. In this case, only
expr1
is set.Three symbolic expressions, one for each component.
Three numerical functions of 3 variables.
- range1, range2, range33-element tuples
Denotes the range of the variables. For example
(x, -5, 5)
.- labelstr, optional
The name of the vector field to be eventually shown on the legend or colorbar. If none is provided, the string representation of the vector will be used.
- colorbarboolean, optional
Show/hide the colorbar. Default to True (colorbar is visible).
- color_funccallable, optional
Define the quiver/streamlines color mapping when
use_cm=True
. It can either be:A numerical function supporting vectorization. The arity must be
f(x, y, z, u, v, w)
.A symbolic expression having at most as many free symbols as
expr1/expr2/expr3
. This only works for quivers plot.None: the default value, which will map colors according to the magnitude of the vector.
- contour_kwdict, optional
A dictionary of keywords/values which is passed to the backend contour function to customize the appearance. Refer to the plotting library (backend) manual for more informations.
- n, n1, n2int, optional
Number of discretization points for the quivers or streamlines in the x/y/z-direction, respectively. Default to 25.
n
is a shortcut to set the same number of discretization points on all directions.- normalizebool, optional
Default to False. If True, the vector field will be normalized, resulting in quivers having the same length. If
use_cm=True
, the backend will color the quivers by the (pre-normalized) vector field’s magnitude. Note: only quivers will be affected by this option.- paramsdict, optional
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.
- quiver_kwdict, optional
A dictionary of keywords/values which is passed to the backend quivers- plotting function to customize the appearance. Refer to the plotting library (backend) manual for more informations.
- slicePlane, list, Expr, optional
Plot the 3D vector field over the provided slice. It can be:
a Plane object from sympy.geometry module.
a list of planes.
an instance of
SurfaceOver2DRangeSeries
orParametricSurfaceSeries
.a symbolic expression representing a surface of two variables.
The number of discretization points will be n1, n2, n3. Note that:
only quivers plots are supported with slices. Streamlines plots are unaffected.
n3 will only be used with planes parallel to xz or yz.
n1, n2, n3 doesn’t affect the slice if it is an instance of
SurfaceOver2DRangeSeries
orParametricSurfaceSeries
.
- streamlinesboolean, optional
Whether to plot the vector field using streamlines (True) or quivers (False). Default to False.
- stream_kwdict, optional
A dictionary of keywords/values which is passed to the backend streamlines-plotting function to customize the appearance.
By default, the streamlines will start at the boundaries of the domain where the vectors are pointed inward. Depending on the vector field, this may results in too tight streamlines. Use the
starts
keyword argument to control the generation of streamlines:starts=None
: the default aforementioned behaviour.starts=dict(x=x_list, y=y_list, z=z_list)
: specify the starting points of the streamlines.starts=True
: randomly create starting points inside the domain. In this setup we can set the number of starting point withnpoints
(default value to 200).
If 3D streamlines appears to be cut short inside the specified domain, try to increase
max_prop
(default value to 5000).
- Returns:
- serieslist
If
slice
is not set, the function returns a list containing one instance ofVector3DSeries
. Conversely, it returns a list containing instances ofSliceVector3DSeries
.
See also
Examples
3D vector field.
from sympy import * from spb import * var("x:z") graphics( vector_field_3d(z, y, x, (x, -10, 10), (y, -10, 10), (z, -10, 10), n=8, quiver_kw={"scale": 0.5, "line_width": 0.1, "head_size": 10}), backend=KB, xlabel="x", ylabel="y", zlabel="z")
3D vector field with 3 orthogonal slice planes.
from sympy import * from spb import * var("x:z") graphics( vector_field_3d(z, y, x, (x, -10, 10), (y, -10, 10), (z, -10, 10), n=8, use_cm=False, quiver_kw={"scale": 0.25, "line_width": 0.1, "head_size": 10}, slice=[ Plane((-10, 0, 0), (1, 0, 0)), Plane((0, 10, 0), (0, 2, 0)), Plane((0, 0, -10), (0, 0, 1))] ), backend=KB, grid=False, xlabel="x", ylabel="y", zlabel="z",)
3D vector streamlines starting at a 300 random points:
from sympy import * from spb import * import k3d var("x:z") graphics( vector_field_3d(z, -x, y, (x, -3, 3), (y, -3, 3), (z, -3, 3), n=40, streamlines=True, stream_kw=dict( starts=True, npoints=400, width=0.025, color_map=k3d.colormaps.matplotlib_color_maps.viridis ) ), backend=KB, xlabel="x", ylabel="y", zlabel="z")
3D vector streamlines starting at the XY plane. Note that the number of discretization points of the plane controls the numbers of streamlines.
from sympy import * from spb import * import k3d var("x:z") u = -y - z v = x + y / 5 w = S(1) / 5 + (x - S(5) / 2) * z s = 10 # length of the cubic discretization volume # create an XY plane with n discretization points along each direction n = 8 p = plane( Plane((0, 0, 0), (0, 0, 1)), (x, -s, s), (y, -s, s), (z, -s, s), n1=n, n2=n)[0] xx, yy, zz = p.get_data() graphics( vector_field_3d( u, v, w, (x, -s, s), (y, -s, s), (z, -s, s), n=40, streamlines=True, stream_kw=dict( starts=dict(x=xx, y=yy, z=zz), width=0.025, color_map=k3d.colormaps.matplotlib_color_maps.plasma )), title=r"Rössler \, attractor", xlabel="x", ylabel="y", zlabel="z", backend=KB, grid=False)
Visually verify the normal vector to a circular cone surface. The following steps are executed:
compute the normal vector to a circular cone surface. This will be the vector field to be plotted.
plot the cone surface for visualization purposes (use high number of discretization points).
plot the cone surface that will be used to slice the vector field (use a low number of discretization points). The data series associated to this plot will be used in the
slice
keyword argument in the next step.plot the sliced vector field.
combine the plots of step 4 and 2 to get a nice visualization.
from sympy import tan, cos, sin, pi, symbols from spb import * from sympy.vector import CoordSys3D, gradient u, v = symbols("u, v") N = CoordSys3D("N") i, j, k = N.base_vectors() xn, yn, zn = N.base_scalars() t = 0.35 # half-cone angle in radians expr = -xn**2 * tan(t)**2 + yn**2 + zn**2 # cone surface equation g = gradient(expr) n = g / g.magnitude() # unit normal vector n1, n2 = 10, 20 # number of discretization points for the vector field # cone surface to discretize vector field (low numb of discret points) cone_discr = surface_parametric( u / tan(t), u * cos(v), u * sin(v), (u, 0, 1), (v, 0 , 2*pi), n1=n1, n2=n2)[0] graphics( surface_parametric( u / tan(t), u * cos(v), u * sin(v), (u, 0, 1), (v, 0 , 2*pi), rendering_kw={"opacity": 1}, wireframe=True, wf_n1=n1, wf_n2=n2, wf_rendering_kw={"width": 0.004}), vector_field_3d( n, range1=(xn, -5, 5), range2=(yn, -5, 5), range3=(zn, -5, 5), use_cm=False, slice=cone_discr, quiver_kw={"scale": 0.5, "pivot": "tail"} ), backend=KB)