vectorialcalculus (version 1.0.5)

solid_spherical3d: Solid in spherical coordinates with Plotly visualization and volume

Description

Draws a three-dimensional solid described in spherical coordinates by:

• a radial variable r between R1(theta, phi) and R2(theta, phi),

• an azimuthal angle theta in the interval [theta_range[1], theta_range[2]] (in radians),

• a polar angle phi in the interval [phi_range[1], phi_range[2]] (in radians).

The function uses the standard convention for spherical coordinates: theta is the azimuth (angle in the xy-plane) and phi is the polar angle measured from the positive z-axis.

Optionally, the volume of the solid is computed using the spherical volume element. The exact integral has the form:

• inner integral: from r = R1(theta, phi) to r = R2(theta, phi) of r^2 * sin(phi) dr,

• outer integrals: over phi in [phi_min, phi_max] and theta in [theta_min, theta_max].

Equivalently, for each pair (theta, phi) one integrates (R2(theta, phi)^3 - R1(theta, phi)^3) / 3 * sin(phi) over the angular rectangle.

Usage

solid_spherical3d(
  R1,
  R2,
  theta_range = c(0, 2 * pi),
  phi_range = c(0, pi),
  n_theta = 160,
  n_phi = 120,
  plot = TRUE,
  show_surfaces = c(TRUE, TRUE),
  colorscales = list("Blues", "Reds"),
  opacities = c(0.3, 0.35),
  show_surface_grid = TRUE,
  surface_grid_color = "rgba(60,80,200,0.25)",
  surface_grid_width = 1,
  scene = list(aspectmode = "data", xaxis = list(title = "x"), yaxis = list(title = "y"),
    zaxis = list(title = "z")),
  bg = list(paper = "white", plot = "white"),
  compute_volume = FALSE,
  vol_method = c("adaptive", "grid"),
  n_th_vol = 600,
  n_ph_vol = 400
)

Value

A list with:

• theta_seq, phi_seq: the parameter sequences used for plotting,

• R1_surf, R2_surf: lists containing the matrices X, Y, Z for the two boundary surfaces (or NULL if the corresponding surface is not shown),

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

• volume: NULL if compute_volume = FALSE, or a list with the numeric volume estimate, the method used and additional metadata when compute_volume = TRUE.

Arguments

R1, R2

Functions function(theta, phi) giving the inner and outer radius, respectively, as numeric scalars.

theta_range

Numeric vector of length 2, c(theta_min, theta_max), giving the azimuth interval in radians.

phi_range

Numeric vector of length 2, c(phi_min, phi_max), giving the polar angle interval in radians.

n_theta, n_phi

Mesh resolution for the two boundary surfaces. Each surface is sampled on an n_phi x n_theta grid.

plot

Logical. If TRUE, the solid boundaries are drawn with plotly.

show_surfaces

Logical vector of length 2 indicating which spherical shells to show in the plot, in the order c(r = R1, r = R2).

colorscales

Colorscales for the two surfaces. You can pass:

• a single Plotly colorscale (string, single color, or vector of colors) applied to both surfaces, or

• a list of length 2, with one colorscale per surface.

Flat colors such as "#2a9d8f" or "rgba(0,0,0,0.6)" are also accepted.

opacities

Numeric vector of length 1 or 2 giving the opacity of the two surfaces.

show_surface_grid

Logical. If TRUE, draws grid lines on the surfaces.

surface_grid_color, surface_grid_width

Color and width for the surface grid lines.

scene

Plotly 3D scene settings. By default the aspect mode is "data" and each axis has a title.

bg

Background colors, typically a list of the form list(paper = "white", plot = "white").

compute_volume

Logical. If TRUE, the volume of the solid is approximated numerically using the spherical volume integral.

vol_method

Character string indicating the integration method for the volume: "adaptive" uses nested stats::integrate, while "grid" uses the trapezoidal rule on a regular grid.

n_th_vol, n_ph_vol

Integer resolutions for the grid method in the azimuth and polar directions, respectively (ignored when vol_method = "adaptive").

Examples

if (interactive()) {
# Example 1: Spherical shell: a <= r <= b, independent of angles
R1 <- function(th, ph) 0.8
R2 <- function(th, ph) 1.2
out <- solid_spherical3d(
  R1, R2,
  theta_range = c(0, 2*pi),
  phi_range   = c(0, pi),
  plot = TRUE,
  colorscales = list("Blues", "Reds"),
  opacities   = c(0.25, 0.35),
  compute_volume = TRUE
)
out$volume$estimate       # approximately 4/3 * pi * (1.2^3 - 0.8^3)

# Example 2: Spherical cap: 0 <= r <= 1, phi in [0, pi/3]
R1 <- function(th, ph) 0
R2 <- function(th, ph) 1
out2 <- solid_spherical3d(
  R1, R2,
  theta_range = c(0, 2*pi),
  phi_range   = c(0, pi/3),
  plot = TRUE,
  compute_volume = TRUE
)
out2$volume$estimate      # analytic value matches the standard spherical cap formula
}