streamlines: Draw streamlines of a two-dimensional vector field

In cooltools: Practical Tools for Scientific Computation and Visualisation

Draw streamlines of a two-dimensional vector field

Description

Draws streamlines of a planar vector field f(x,y) by integrating forward and backward from a set of starting points. Starting points can be provided as a single integer, a length-2 integer vector, or an n \times 2 matrix of coordinates.

Usage

streamlines(
  f,
  xlim,
  ylim,
  points = 20,
  nsteps = 100,
  arrows = FALSE,
  add = FALSE,
  ...
)

Arguments

f	A function of the form 'f(x, y)' returning an n \times 2 matrix of vector components, where the first column is the x-component and the second column is the y-component.
xlim	Numeric vector of length 2 giving the x-limits of the plot.
ylim	Numeric vector of length 2 giving the y-limits of the plot.
points	Starting points for the streamlines. This can be: a single integer, interpreted as the number of quasi-random starting points; a numeric vector of length 2, interpreted as the numbers of starting points in x- and y-direction; a numeric matrix with 2 columns, giving explicit starting coordinates.
nsteps	Integer giving the number of integration steps in each direction.
arrows	Controls where arrows are drawn. This can be: 'FALSE': no arrows are drawn; 'TRUE': one arrow is drawn on every streamline, centered on its starting point and aligned with the local field direction; an integer vector: arrows are drawn only on the corresponding streamlines, using the indices of the starting points; a numeric matrix with 2 columns: arrows are drawn at the specified coordinates, aligned with the local field direction at those points.
add	Logical; if 'FALSE' a new plot is created, otherwise streamlines are added to the existing plot.
...	Further graphical parameters passed to [graphics::lines()] and [graphics::arrows()].

Details

The integration uses a fixed step length based on the plot diagonal,

d = \sqrt{dx^2 + dy^2} / nsteps,

where 'dx = diff(range(xlim))' and 'dy = diff(range(ylim))'. At each step, only the direction of the vector field is used, via [unitvector()], so the result shows streamlines of the field rather than trajectories with speed information.

If 'add = FALSE', a new plot is initialized using [plot()].

Arrows are drawn along the local field direction. If 'arrows = TRUE', each arrow is centered on the streamline starting point. If 'arrows' is a matrix of coordinates, the arrows are placed at those coordinates, regardless of whether they lie exactly on a streamline.

Value

Invisibly returns a list with components:

• 'forward': array of forward-integrated coordinates;

• 'backward': array of backward-integrated coordinates;

• 'start': matrix of starting coordinates.

Examples

f = function(x,y) {
  vx = -x-y
  vy = -y+(x-0.5)
  cbind(vx,vy)
}

streamlines(f, c(-1,1), c(-1,1), 50, 500, col = "#5555ff")
streamlines(f, c(-1,1), c(-1,1), 20, 200, arrows = TRUE, add = FALSE,
            col = "#5555ff")

cooltools documentation built on Sept. 11, 2026, 5:06 p.m.