vectorialcalculus (version 1.0.5)

vector_field3d: 3D vector field in a curvilinear prism

Description

Displays a three-dimensional vector field inside a solid region whose bounds in the variables x, y and z are defined by user-supplied functions. The region is described by an interval for x, lower and upper bounds in the y direction depending on x, and lower and upper bounds in the z direction that may depend on both x and y. The function samples this volume on a regular grid and draws arrows representing the vector field using plotly.

Usage

vector_field3d(
  F,
  H1,
  H2,
  G1,
  G2,
  a,
  b,
  NX = 8,
  NY = 6,
  NZ = 6,
  plot = TRUE,
  arrows = c("both", "line", "cone", "none"),
  arrow_scale = 0.08,
  normalize_bias = 1,
  normal_color = "black",
  normal_width = 1.5,
  arrow_color = "black",
  arrow_opacity = 0.9,
  arrow_size = 0.35,
  scene = list(aspectmode = "data", xaxis = list(title = "x"), yaxis = list(title = "y"),
    zaxis = list(title = "z")),
  bg = list(paper = "white", plot = "white")
)

Value

A list with:

• points: a data frame with base positions x, y, z and the magnitude of the field at each point,

• segments: a data frame with columns x0, y0, z0, x1, y1, z1 describing the arrow shafts,

• fig: a plotly object when plot = TRUE, otherwise NULL.

Arguments

F

A function function(x, y, z) returning a numeric vector of length three, interpreted as c(Fx, Fy, Fz).

H1, H2

Functions of one variable x giving the lower and upper bounds in the y direction.

G1, G2

Functions of two variables x and y giving the lower and upper bounds in the z direction.

a, b

Numeric endpoints of the interval for x. It is assumed that b > a.

NX, NY, NZ

Integers greater than or equal to one giving the grid density in the three parameter directions. Each parameter is sampled using a regular sequence between zero and one with N + 1 points.

plot

Logical; if TRUE, the vector field is drawn using plotly.

arrows

Character string indicating the arrow mode. Allowed values are "both", "line", "cone" and "none".

arrow_scale

Global length scale for arrows, expressed as a fraction of the largest span of the bounding box.

normalize_bias

Numeric saturation bias used in the scaling of the vector norm. Larger values make the arrow lengths saturate earlier.

normal_color

Color for the arrow shafts (line segments).

normal_width

Numeric width of the arrow shafts.

arrow_color

Color for the arrow heads (cones or chevrons).

arrow_opacity

Numeric opacity for arrow heads when cones are available.

arrow_size

Relative size of arrow heads with respect to arrow_scale.

scene

List with 3D scene options for plotly.

bg

List with background colors for the figure, typically with entries paper and plot.

Details

The domain is parameterized by three normalized parameters, one for each direction. For each grid point, the corresponding physical coordinates in x, y and z are obtained by linear interpolation between the lower and upper bounds. The vector field is evaluated at each of these points.

Arrow lengths are scaled using a saturated version of the vector norm. This avoids extremely long arrows when the magnitude of the field varies strongly across the region. A bias parameter controls how quickly the lengths approach saturation: small magnitudes produce short arrows and large magnitudes are capped so that they remain visible without dominating the picture.

Depending on the selected mode, the function can:

• draw only line segments representing the arrow shafts,

• draw only arrow heads (cones or chevrons),

• or combine both shafts and heads.

The plotted figure can be customized through colors, opacity settings, line widths and standard plotly scene options. If plotting is disabled, the function still returns the sampled data for further processing.

Examples

if (interactive()) {
H1 <- function(x) -1 - x
H2 <- function(x)  1 - x^2
G1 <- function(x, y) y
G2 <- function(x, y) y + 1

F <- function(x, y, z) c(-y, x, 1)

vector_field3d(
  F, H1 = H1, H2 = H2, G1 = G1, G2 = G2,
  a = -1, b = 1, NX = 8, NY = 6, NZ = 6,
  plot = TRUE, arrows = "both",
  arrow_scale = 0.08, normalize_bias = 1,
  normal_color = "rgba(0,0,0,0.6)", normal_width = 2,
  arrow_color  = "#1d3557", arrow_opacity = 0.95, arrow_size = 0.35
)
}