Help for package acousticTS

Title:

Physics-Based Models for Acoustic Target Strength

Version:

2.0.6

See file inst/COPYRIGHTS.

Description:

Acoustic target strength (TS) represents the intensity of an echo returning from an individual scatterer such as bubbles, fish, or zooplankton. TS can be used to convert integrated or volumetric backscatter collected from fisheries acoustic surveys into units of number density (e.g. animals per m^3), abundance (e.g. number of animals), and biomass (e.g. kg). This parameter can also be used to aid in classifying backscatter, such as separating likely echoes of large predatory fish (e.g. adult cod) from smaller prey (e.g. shrimp). One way to estimate TS is to use physics-based models to calculate theoretical TS that comprise exact and approximate solutions as well as analytical approaches. The models provided can help provide TS estimates over broad statistical distributions of model parameters. Applications are described by Lucca et al. (2023) <doi:10.1121/10.0022459>, with fisheries-acoustics principles from Simmonds and MacLennan (2005) <doi:10.1002/9780470995303>.

License:

GPL-3

URL:

https://brandynlucca.github.io/acousticTS/, https://doi.org/10.5281/zenodo.7600659

BugReports:

https://github.com/brandynlucca/acousticTS/issues

Depends:

R (≥ 4.0.0)

Imports:

grDevices, graphics, methods, parallel, pbapply, Rcpp, stats, tools, utils

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0)

LinkingTo:

BH, Rcpp, RcppArmadillo

VignetteBuilder:

knitr, rmarkdown

Config/testthat/edition:

Encoding:

UTF-8

Language:

en-US

Collate:

'RcppExports.R' 'acoustics.R' 'bessel-cylindrical.R' 'bessel-spherical.R' 'constants.R' 'utilities-scatterer.R' 'create_scatterer.R' 'create_shape.R' 'data.R' 'harmonics.R' 'math.R' 'models.R' 'model-bcms.R' 'model-bbfm.R' 'model-dwba.R' 'model-pcdwba.R' 'model-ecms.R' 'model-essms.R' 'model-vesms.R' 'model-fcms.R' 'model-hpa.R' 'model-krm.R' 'model-psms.R' 'model-tmm-helpers.R' 'model-tmm-spherical.R' 'model-tmm-spheroidal.R' 'model-tmm.R' 'tmm-scattering.R' 'tmm-orientation.R' 'tmm-diagnostics.R' 'tmm-bistatic.R' 'tmm-plotting.R' 'model-sdwba.R' 'model-soems.R' 'model-sphms.R' 'model-trcm.R' 'validation-registry.R' 'pkgdown-helpers.R' 'scatterer.R' 'scatterer_plot.R' 'scatterer_reforge.R' 'shapes.R' 'show.R' 'simulation.R' 'spheroidal.R' 'utilities.R' 'utilities-init.R' 'utilities-modal.R' 'utilities-plotting.R' 'utilities-geometry.R' 'shape_manipulation.R' 'canonicalize_shape.R' 'validation.R'

Config/roxygen2/version:

8.1.0

NeedsCompilation:

yes

Packaged:

2026-09-15 19:00:48 UTC; Brandyn

Author:

Brandyn Lucca

[aut, cre, cph], Arnie Lee Van Buren [ctb, cph] (Author and copyright holder of upstream prolate_swf code adapted for this package), Jeffrey E. Boisvert [ctb] (Coauthor of upstream prolate_swf code adapted for this package)

Maintainer:

Brandyn Lucca <brandyn.lucca@gmail.com>

Repository:

CRAN

Date/Publication:

2026-09-26 17:00:34 UTC

Arbitrary body shape

Description

Arbitrary body shape

Value

An object of the Arbitrary S4 class.

Examples

methods::getClass("Arbitrary")

Backboned fish (BBF) object/class.

Description

A S4 class that stores a fluid-like flesh component together with an explicit elastic backbone component for swimbladder-less fish applications where those two structures should remain separate. The body and backbone each retain their own geometry, orientations, and material properties. This class is intended to support composite flesh-plus-backbone model development and future extensions where additional internal structures may need to be carried alongside the body.

Value

An object of the BBF S4 class.

Examples

methods::getClass("BBF")

Body-backbone composite model (BBFM)

Description

Computes a coherent composite backscatter prediction for swimbladder-less fish represented as a weakly scattering flesh body plus an explicit elastic backbone. The flesh contribution is evaluated with the distorted-wave Born approximation (DWBA), while the backbone contribution is evaluated with the elastic cylinder modal-series solution (ECMS). The backbone amplitude is then translated into the stored body coordinate frame using a phase factor based on the backbone centroid before the two complex amplitudes are summed.

Value

No value; this help topic documents the BBFM model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "BBFM",
  sound_speed_sw,
  density_sw,
  m_limit
)

Arguments

sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
m_limit: Optional modal truncation limit passed to the backbone ECMS solve.

Theory

The model follows the same structural decomposition used for swimbladder-less mackerel by Gorska, Ona, and Korneliussen (2005): the flesh is treated as a weakly scattering fluid-like body, and the backbone is treated as an elastic cylindrical structure. In this implementation, the total complex backscattering amplitude is

f_{bs} = f_{\mathrm{flesh}} + f_{\mathrm{backbone}} \exp\left\{ 2 i k_{sw} v_c \right\},

where f_{\mathrm{flesh}} is obtained from DWBA, f_{\mathrm{backbone}} is obtained from ECMS, and v_c = x_c \cos \theta + z_c \sin \theta is the projection of the stored backbone centroid onto the backscatter direction.

References

Gorska, N., Ona, E., and Korneliussen, R. (2005). Acoustic backscattering by Atlantic mackerel as being representative of fish that lack a swimbladder. Backscattering by individual fish. ICES Journal of Marine Science, 62: 984-995.

Stanton, T.K. (1988). Sound scattering by cylinders of finite length. II. Elastic cylinders. The Journal of the Acoustical Society of America, 83: 64-67.

Stanton, T.K. (1989). Sound scattering by cylinders of finite length. III. Deformed cylinders. The Journal of the Acoustical Society of America, 86: 691-705.

Stanton, T.K., Chu, D., and Wiebe, P.H. (1998). Sound scattering by several zooplankton groups. II. Scattering models. The Journal of the Acoustical Society of America, 103: 236-253.

Examples

subset(available_models(), model == "bbfm")

Bent cylinder modal series (BCMS) solution

Description

Computes backscatter from straight and uniformly bent finite cylinders by combining the exact finite-cylinder modal-series kernel with the equivalent coherent-length correction used for uniformly bent cylinders near normal incidence.

Value

No value; this help topic documents the BCMS model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "BCMS",
  boundary,
  sound_speed_sw,
  density_sw,
  m_limit
)

Arguments

boundary: Boundary condition at the cylinder surface. One of "fixed_rigid", "pressure_release", "liquid_filled", or "gas_filled".
sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
m_limit: Optional model truncation limit used to cap the number of retained cylindrical modes.

References

Stanton, T.K. (1988). Sound scattering by cylinders of finite length. I. Fluid cylinders. The Journal of the Acoustical Society of America, 83: 55-63.

Stanton, T.K. (1989). Sound scattering by cylinders of finite length. III. Deformed cylinders. The Journal of the Acoustical Society of America, 85: 232-237.

Stanton, T.K., Chu, D., Wiebe, P.H., and Clay, C.S. (1993). Average echoes from randomly oriented random-length finite cylinders: zooplankton models. The Journal of the Acoustical Society of America, 94: 3463-3472.

Examples

subset(available_models(), model == "bcms")

Solid and calibration sphere (CAL) object/class.

Description

A S4 class that provides slots to contain relevant metadata for solid sphere objects belonging to the CAL-class scatterers. This object is created using parameters specific to the outer shell. The default behavior of this object is to only reference these outer elastic shell properties with few exceptions that are model-dependent. CAL inherits from the broader elastic-based ELA class rather than from ESS, because calibration targets are solid elastic bodies rather than elastic shells. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the CAL S4 class.

Examples

methods::getClass("CAL")

Composite scatterer (CSC) object/class.

Description

A shared parent S4 class for composite scatterers that retain a primary body component together with one or more additional anatomically distinct sub-components. The CSC-class is intended to provide modular scaffolding for multi-component biological targets, such as swimbladder-bearing fish and swimbladder-less fish represented as flesh plus backbone. It stores the primary body, a general component list, the shared model output slot, and shape metadata without implying any one specific resonant or elastic inclusion type.

Value

An object of the CSC S4 class.

Examples

methods::getClass("CSC")

Cylindrical body shape

Description

Cylindrical body shape

Value

An object of the Cylinder S4 class.

Examples

methods::getClass("Cylinder")

Distorted wave Born approximation (DWBA) for weak scatterers

Description

Calculates backscatter for fluid-like weak scatterers using the distorted wave Born approximation (DWBA). Frequencies in Hz; sound speed in m/s; density in kg/m^3. Material properties may be provided as contrasts or absolute values (contrasts derived relative to seawater).

Value

No value; this help topic documents the DWBA model.

Usage

This model is accessed via:

target_strength(
  ...,
  model="dwba",
  sound_speed_sw,
  density_sw
)

Arguments

sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).

Theory

The DWBA approach is derived under the weak scattering assumption, meaning that the differences in compressibility (\kappa) and density (\rho) between the scatterer and surrounding fluid are sufficiently small to linearize the acoustic scattering problem. This linearization allows the scattered field to be expressed as an integral over the scatterer volume.

The far-field backscattering amplitude is given by:

f_{bs} = \frac{k_1}{4\pi} \int \int \int\limits_v (\gamma_\kappa - \gamma_\rho) e^{2i k_2 \cdot r_v} dv

where

\gamma_\kappa = \frac{\kappa_2 - \kappa_1}{\kappa_1}, \quad \gamma_\rho = \frac{\rho_2 - \rho_1}{\rho_2},

and

\kappa = (\rho c^2)^{-1}.

where c is the sound speed (m s^-1). For elongated bodies, the volume integral reduces to a line intergral along the body axis:

f_{bs} = \frac{k_1}{4} \int_{r_{pos}} (\gamma_\kappa - \gamma_\rho) e^{2i k_2 \cdot r_{pos}} \frac{\text{J}_1(2 k_2 a \cos \beta_{tilt})}{\cos \beta_{tilt}} |dr_{pos}|,

where a is the local radius and \beta_{tilt} the local tilt angle. The cylindrical Bessel function of the first kind of order 1, \text{J}_1, accounts for the circular cross-section of each segment. The wavenumber k_2 is evaluated inside the scatterer.

Assumptions

The DWBA assumes that the scatterer is weakly inhomogenous where the material property contrasts for the interior (c_2, \rho_2) and surrounding fluid (c_1, \rho_1) where:

g = \frac{\rho_2}{\rho_1} \approx 1, \quad h = \frac{c_2}{c_1} \approx 1.

In practice, c_2 and \rho_2 within 5% of c_1 and \rho_1, respectively, can be considered to be sufficient for the weak scattering assumption whereby:

|h - 1| \le 0.05, \quad |g - 1| \le 0.05.

This model also assumes that the scatterer's body has no sharp edges or irregularities, and its cross-section is symmetric around the longitudinal axis. This allows the scattering integral to be reduced to a line integral along the body axis in the first place, simplifying the computation of phase contributions from different segments. Moreover, this enables the body to be discretized into along-axis segments that can approximate arbitrary body shapes. Since the body is axisymmetric and smooth, this further allows the DWBA to be applied for arbitrary orientation angles without additional correction terms.

The DWBA provides a first-order approximation that neglects multiple scattering within the body whereby secondary interactions between different parts of the body are ignored. This is valid for weakly scattering objects where the amplitude of scattered waves is small and is consistent with the Born approximation in wave physics. This model also disregards any elastic or shelled effects, treating scatterers are being purely fluid-like. Consequently, the lack of internal elasticity means there is no support for shear waves or resonances due to solid boundaries. Mathematically, this means that only the contrasts in compressibility and density between the scatterer and the surrounding medium contribute to the scattered field.

Implementation

The model extracts geometric and acoustic parameters from the input object, constructs rotation matrices and wavenumber matrices, and evaluates the integral numerically for each frequency of interest. The DWBA is computationally efficient and handles elongated, weakly scattering targets such as zooplankton and small fish.

References

Morse, P.M., and Ingard, K.U. (1968). Theoretical Acoustics. Princeton University Press.

Stanton, T.K., Chu, D., and Wiebe, P.H. (1998). Sound scattering by several zooplankton groups. II. Scattering models. The Journal of the Acoustical Society of America, 103, 236-253.

Examples

subset(available_models(), model == "dwba")

Elastic cylinder modal series (ECMS) solution

Description

Computes backscatter from straight and uniformly bent finite elastic cylinders by combining the phase-shift solution for an infinite elastic cylinder with the finite-length coherence factor used for normal and near-normal incidence, plus the Fresnel coherence correction used for uniformly bent cylinders. In the current package class system, the elastic cylinder is carried most naturally by an ESS-class cylinder within the broader elastic-based ELA family, with the elastic-cylinder properties stored on the shell slot. Legacy FLS-class cylinders are also accepted as geometry carriers for backward compatibility.

Value

No value; this help topic documents the ECMS model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "ECMS",
  sound_speed_sw,
  density_sw,
  density_body,
  sound_speed_longitudinal_body,
  sound_speed_transversal_body,
  m_limit
)

Arguments

sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
density_body: Elastic-cylinder density (kg~m^{-3}). If omitted, the model uses the density stored on the scatterer body.
sound_speed_longitudinal_body: Longitudinal wave speed in the elastic cylinder (m~s^{-1}).
sound_speed_transversal_body: Transversal (shear) wave speed in the elastic cylinder (m~s^{-1}).
m_limit: Optional model truncation limit used to cap the number of retained cylindrical modes.

References

Faran, J.J. (1951). Sound scattering by solid cylinders and spheres. The Journal of the Acoustical Society of America, 23: 405-418.

Stanton, T.K. (1988). Sound scattering by cylinders of finite length. II. Elastic cylinders. The Journal of the Acoustical Society of America, 83: 64-67.

Stanton, T.K. (1989). Sound scattering by cylinders of finite length. III. Deformed cylinders. The Journal of the Acoustical Society of America, 86: 691-705.

Examples

subset(available_models(), model == "ecms")

Elastic-based scatterer (ELA) object/class.

Description

A shared parent S4 class for elastic-based scatterers. The ELA-class collects the slots common to solid elastic targets such as calibration spheres (CAL) and elastic-shelled targets (ESS), without implying a particular internal structure such as a shell or homogeneous elastic solid. See Scatterer for a more detailed description of the shared object organization.

Value

An object of the ELA S4 class.

Examples

methods::getClass("ELA")

Elastic shelled scatterer (ESS) object/class.

Description

A S4 class that provides slots to contain relevant metadata for elastic shelled scatterers/objects belonging to the ESS-class. This object can be created using values for both an outer shell and internal tissues, if applicable. The default behavior for this type of this object is to only reference the outer shell with few exceptions that are model-dependent. ESS inherits from the broader elastic-based ELA class. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the ESS S4 class.

Examples

methods::getClass("ESS")

Elastic-shelled sphere modal series (ESSMS) solution

Description

Calculates the far-field scattering amplitude and related quantities elastic shelled sphere using the modal series solution, as described by Goodman and Stern (1962).

Value

No value; this help topic documents the ESSMS model.

Usage

This model is accessed via:

target_strength(
  ...,
  model="essms",
  sound_speed_sw,
  density_sw,
  m_limit
)

Arguments

sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
m_limit: Optional model truncation limit used to cap the number of modes in the numerical calculation. By default, this is set to the maximum value of ka + 10.

Theory

The elastic-shelled sphere model solves the acoustic scattering problem by expanding the incident and scattered fields in terms of spherical Bessel and Hankel functions and Legendre polynomials. The displacement field in the shell is represented as the sum of a scalar potential and a vector potential:

\mathbf{u} = \nabla \phi + \nabla \times \mathbf{\Psi}

where \phi and \mathbf{\Psi} satisfy the Helmholtz equations with velocities determined by the elastic properties of the shell:

(1/c_L^2) \frac{\partial^2 \phi}{\partial t^2} = \nabla^2 \phi, \qquad (1/c_T^2) \frac{\partial^2 \mathbf{\Psi}}{\partial t^2} = \nabla^2 \mathbf{\Psi}

with c_L = \sqrt{(\lambda + 2\mu)/\rho} (longitudinal) and c_T = \sqrt{\mu/\rho} (transverse) wave speeds, where \lambda and \mu are the Lamé parameters and \rho is the shell density.

The scattered field is expanded as:

f_{bs} = -\frac{i}{k} \sum_{m=0}^{\infty} (2m+1) b_m P_m(\cos\theta)

where k is the wavenumber in the surrounding fluid, P_m is the Legendre polynomial of order m, and b_m are the modal coefficients determined by the shell and fluid properties.

The modal coefficients b_m are determined by enforcing boundary conditions at the shell-fluid interfaces, resulting in a system of six equations for each mode. These are solved using Cramer's rule as the ratio of two 6 \times 6 determinants.

At mode 0:

b_m(0) = \frac{ \left| \begin{array}{ccccc} a_1 & \alpha_{12} & \alpha_{14} & 0 & 0 \\ a_2 & \alpha_{22} & \alpha_{24} & 0 & 0 \\ 0 & \alpha_{42} & \alpha_{44} & \alpha_{46} & 0 \\ 0 & \alpha_{52} & \alpha_{54} & \alpha_{56} & 0 \\ 0 & \alpha_{62} & \alpha_{64} & \alpha_{66} & 0 \end{array} \right| }{ \left| \begin{array}{ccccc} \alpha_{11} & \alpha_{12} & \alpha_{14} & 0 & 0 \\ \alpha_{21} & \alpha_{22} & \alpha_{24} & 0 & 0 \\ 0 & \alpha_{42} & \alpha_{44} & \alpha_{46} & 0 \\ 0 & \alpha_{52} & \alpha_{54} & \alpha_{56} & 0 \\ 0 & \alpha_{62} & \alpha_{64} & \alpha_{66} & 0 \end{array} \right| }

At modes greater than 0:

b_m(m) = -i^m (2m+1) \frac{ \left| \begin{array}{cccccc} a_1 & \alpha_{12} & \alpha_{13} & \alpha_{14} & \alpha_{15} & 0 \\ a_2 & \alpha_{22} & \alpha_{23} & \alpha_{24} & \alpha_{25} & 0 \\ 0 & \alpha_{32} & \alpha_{33} & \alpha_{34} & \alpha_{35} & 0 \\ 0 & \alpha_{42} & \alpha_{43} & \alpha_{44} & \alpha_{45} & \alpha_{46} \\ 0 & \alpha_{52} & \alpha_{53} & \alpha_{54} & \alpha_{55} & \alpha_{56} \\ 0 & \alpha_{62} & \alpha_{63} & \alpha_{64} & \alpha_{65} & \alpha_{66} \end{array} \right| }{ \left| \begin{array}{cccccc} \alpha_{11} & \alpha_{12} & \alpha_{13} & \alpha_{14} & \alpha_{15} & 0 \\ \alpha_{21} & \alpha_{22} & \alpha_{23} & \alpha_{24} & \alpha_{25} & 0 \\ 0 & \alpha_{32} & \alpha_{33} & \alpha_{34} & \alpha_{35} & 0 \\ 0 & \alpha_{42} & \alpha_{43} & \alpha_{44} & \alpha_{45} & \alpha_{46} \\ 0 & \alpha_{52} & \alpha_{53} & \alpha_{54} & \alpha_{55} & \alpha_{56} \\ 0 & \alpha_{62} & \alpha_{63} & \alpha_{64} & \alpha_{65} & \alpha_{66} \end{array} \right| }

The elements of these matrices depend on the shell's elastic moduli, thickness, densities, and the acoustic properties of the interior and exterior fluids. The exact values for each element can be calcaulted using equations provided by Goodman and Stern (1962) and Stanton (1990). Since \theta = \pi in the backscattering case, the equation for f_{bs} becomes:

f_{bs} = -\frac{i}{k} \sum_{m=0}^{\infty} (2m+1) b_m P_m(\cos\theta) \\ \phantom{f_{bs}} = -\frac{i}{k} \sum_{m=0}^{\infty} (2m+1) b_m P_m(-1) \\ \phantom{f_{bs}} = -\frac{i}{k} \sum_{m=0}^{\infty} (2m+1) b_m (-1)^m

Implementation

C++

The computation for b_m was done in C++ due to relatively large computational costs with increasing ka (and subsequently larger limits for m) and the efficiency in solving the systems of linear equations containing complex values. Since each matrix is a square, this implementation specifically utilizes lower-upper (LU) decomposition to break down the matrices into the products of the resulting lower and upper triangular matrices. However, this means that the determinant computations are sensitive to ill-conditioned matrices that can amplify numerical errors.

There are guards in-place that partially address singularity issues when the denominator is 0. The algorithm does not handle near-singular matrices directly, but it will raise a warning when a matrix is ill-conditioned. This is determined based on the pivot ratio from the calculated condition number. Partial pivoting and row-scaling are also incorporated to improve numerical stability and reduce the effect of high-leverage values in a matrix.

Modal Truncation

The maximum number of terms for n is chosen as k_w a_{shell} + 10 (rounded to the nearest integer), which is sufficient for convergence in most practical cases.

References

Anderson, V.C. (1950). Sound scattering from a fluid sphere. The Journal of The Acoustical Society of America, 22: 426-431.

Gaunaurd, G.C., and Wertman, W. (1991). Transient acoustic scattering by fluid-loaded elastic shells. International Journal of Solids and Structures, 27: 699-811.

Stanton, T.K. (1990). Sound scattering by spherical and elongated shelled bodies. The Journal of the Acoustical Society of America, 88: 1619-1633.

Examples

subset(available_models(), model == "essms")

Finite cylinder modal series (FCMS) solution

Description

Calculates the far-field scattering amplitude and related quantities for a finite cylinder using the modal series solution, supporting various boundary conditions (rigid, pressure-release, liquid-filled, and gas-filled).

Value

No value; this help topic documents the FCMS model.

Usage

This model is accessed via:

target_strength(
  ...,
  model="fcms",
  boundary,
  sound_speed_sw,
  density_sw,
  m_limit
)

Arguments

boundary: Boundary condition at a cylindrical surface. One of "fixed_rigid", "pressure_release", "liquid_filled", or "gas_filled". See the boundary conditions documentation for more details on these different boundary conditions.
sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
m_limit: Optional model truncation limit used to cap the number of modes in the numerical calculation.

Theory

The modal series solution for a finite cylinder expresses the backscattering amplitude as:

f_{bs} = -\frac{L}{\pi} \frac{\sin(k L \cos \theta)}{k L \cos \theta} \sum_{m=0}^{\infty} i^{m+1} B_m

where L is the cylinder length, k is the wavenumber in the surrounding medium, and \theta is the angle between the cylinder axis and the incident wave direction. The coefficients B_m depend on the boundary condition at the cylinder surface.

Boundary Conditions and Modal Coefficients

Rigid (fixed) cylinder: The normal velocity at the surface is zero. The modal coefficient is:

B_m = (-1)^m \epsilon_m \frac{J_m'(K a)}{H_m^{(1)'}(K a)}

where J_m and H_m^{(1)} are the cylindrical Bessel and Hankel functions of order m, the prime denotes differentiation with respect to the argument, K = k \sin \theta, and a is the cylinder radius. The Neumann factor is \epsilon_0 = 1, \epsilon_m = 2 for m \geq 1.
Pressure-release cylinder: The acoustic pressure at the surface is zero. The modal coefficient is:

B_m = (-1)^m \epsilon_m \frac{J_m(K a)}{H_m^{(1)}(K a)}
Fluid-filled (or gas-filled) cylinder: Both pressure and normal velocity are nonzero at the surface. The modal coefficient is:

B_m = -\epsilon_m / (1 + i C_m)

where

C_m = \frac{ \left[ J_m'(K' a) Y_m(K a) \right] / \left[ J_m(K' a) J_m'(K a) \right] - g h \left[ Y_m'(K a) / J_m'(K a) \right] }{ \left[ J_m'(K' a) J_m(K a) \right] / \left[ J_m(K' a) J_m'(K a) \right] - g h }

Here, Y_m is the cylindrical Bessel function of the second kind, K' = K / h, g is the density contrast (target to medium), and h is the sound speed contrast (target to medium).

Modal Truncation

The modal sum is truncated at a maximum order determined by m_{\max} = \max(\lceil k a \rceil) + 10, which is sufficient for convergence in most practical cases.

References

Stanton, T.K. (1988). Sound scattering by cylinders of finite length. I. Fluid cylinders. The Journal of the Acoustical Society of America, 83: 55-63.

Stanton, T.K. (1989). Sound scattering by cylinders of finite length. III. Deformed cylinders. The Journal of the Acoustical Society of America, 85: 232-237.

Examples

subset(available_models(), model == "fcms")

Fluid-like scatterer (FLS) object/class.

Description

A S4 class that provides slots to contain relevant metadata for scatterers similar to the surrounding fluid medium (i.e fluid-like) belonging to FLS-class scatterers. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the FLS S4 class.

Examples

methods::getClass("FLS")

Generic gas-filled scatterer (GAS) object/class.

Description

A S4 class that provides slots to contain relevant metadata for gas-bearing scatterers belonging to the GAS-class. This object can include simple gas-filled bubbles to other scatterers with gas occlusions, swimbladders, and other internal features, if applicable. The default behavior for this type of object is to only reference the gaseous/fluid feature with exceptions that are model-dependent. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the GAS S4 class.

Examples

methods::getClass("GAS")

High-pass approximation (HPA) scattering model

Description

Computes the far-field scattering amplitude and related quantities spherical and elongated scatterers using a high-pass approximation model. The high-pass model provides a simplified analytical expression for the backscattering cross-section that is valid for all values of ka, where k is the acoustic wavenumber and a is a characteristic dimension of the scatterer. The model is named after the analogy to a two-pole high-pass filter in electrical circuit theory, where the frequency response resembles the backscattering behavior as a function of ka. The high-pass model is computationally efficient and captures the essential physics of acoustic scattering from weakly scattering bodies, including spheres, prolate spheroids, and straight or bent cylinders. Two implementations are available: the Johnson (1977) formulation for fluid spheres, and the Stanton (1989) generalization for spheres, prolate spheroids, and cylinders.

Value

No value; this help topic documents the HPA model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "HPA",
  method,
  deviation_fun,
  null_fun,
  sound_speed_sw,
  density_sw
)

Arguments

method: Method for computing the high-pass model. One of "johnson" (Johnson 1977 formulation for fluid spheres) or "stanton" (Stanton 1989 formulation for spheres, prolate spheroids, and cylinders).
deviation_fun: Function or scalar specifying the expected deviation in the phase of the scattered wave due to shape complexity, flexure, or other factors. Expressed as a function of ka, or as a scalar constant. Default is 1.
null_fun: Function or scalar specifying the expected reduction in scattering amplitude due to nulls in the scattering pattern. Expressed as a function of ka, or as a scalar constant. Default is 1.
sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).

Theory

The high-pass model is based on the observation that the backscattering cross-section of a scatterer can be approximated by a simple analytical expression that captures the low-frequency Rayleigh scattering regime (where \sigma_{bs} \propto (ka)^4) and the high-frequency geometric scattering regime (where \sigma_{bs} approaches a constant). The transition between these regimes is governed by an auxiliary material property parameter, \alpha, which depends on the density contrast g and sound speed contrast h between the scatterer and the surrounding medium. For spheres and prolate spheroids, the auxiliary parameter is given by

\alpha_{\pi s} = \frac{1 - g h^2}{3 g h^2} + \frac{1 - g}{1 + 2g}

and for cylinders and prolate spheroids (in the cylindrical limit), the auxiliary parameter is

\alpha_{\pi c} = \frac{1 - g h^2}{2 g h^2} + \frac{1 - g}{1 + g}

where g is the density contrast (target to medium) and h is the sound speed contrast (target to medium). The reflection coefficient at the scatterer surface is given by

\mathcal{R} = \frac{gh - 1}{gh + 1}

The Johnson (1977) high-pass model for a fluid sphere is expressed as

\sigma_{bs} = \frac{a^2 (ka)^4 \alpha_{\pi s}^2}{1 + \frac{3}{2} (ka)^4}

where a is the spherical radius. This formulation is valid for all ka and provides a good approximation for fluid spheres. The Stanton (1989) high-pass model generalizes this approach to spheres, prolate spheroids, and cylinders, and incorporates empirical terms to account for nulls in the scattering pattern and deviations due to shape complexity. For a sphere, the Stanton formulation is

\sigma_{bs} = \frac{ a^2 (ka)^4 \alpha_{\pi s}^2 \mathcal{G} }{ 1 + \frac{4(ka)^4 \alpha_{\pi s}^2}{\mathcal{R}^2 \mathcal{F}} }

where \mathcal{G} is a null function that accounts for reductions in scattering amplitude at certain frequencies, and \mathcal{F} is a deviation function that accounts for phase variability. For a prolate spheroid, the Stanton formulation is

\sigma_{bs} = \frac{ \frac{1}{9} L^2 (ka)^4 \alpha_{\pi c}^2 \mathcal{G} }{ 1 + \frac{\frac{16}{9}(ka)^4 \alpha_{\pi c}^2} {\mathcal{R}^2 \mathcal{F}} }

where L is the length of the prolate spheroid. For a straight cylinder at angle \theta, the Stanton formulation is

\sigma_{bs} = \frac{ \frac{1}{4} L^2 (Ka)^4 \alpha_{\pi c}^2 s^2 \mathcal{G} }{ 1 + \frac{\pi (Ka)^3 \alpha_{\pi c}^2}{\mathcal{R}^2 \mathcal{F}} }

where K = k \sin \theta, a is the cylindrical radius, and s = \sin(kL \cos \theta) / (kL \cos \theta) accounts for the finite length and orientation of the cylinder. For a bent cylinder with radius of curvature \rho_c relative to the cylinder length L, the Stanton formulation is

\sigma_{bs} = \frac{ \frac{1}{4} L^2 (ka)^4 \alpha_{\pi c}^2 \mathcal{H}^2 \mathcal{G} }{ 1 + \frac{ L^2 (ka)^4 \alpha_{\pi c}^2 \mathcal{H}^2 }{ \rho_c a \mathcal{R}^2 \mathcal{F} } }

where \mathcal{H} = \frac{1}{2} + \frac{1}{2} (\rho_c / L) \sin(L / \rho_c) is an effective length factor that accounts for the curvature. The empirical functions \mathcal{F} and \mathcal{G} are specified by the user as functions of ka, and can be used to fit the model to measured or numerically simulated scattering data. In all cases, the wavenumber satisfies kr \gg 1 and L \ll 2\sqrt{r \lambda}, where r is the distance from the scatterer to the receiver and \lambda is the acoustic wavelength, ensuring that the far-field and elongated object assumptions are valid.

References

Johnson, R.K. (1977). Sound scattering from a fluid sphere revisited. The Journal of the Acoustical Society of America, 61: 375-377.

Johnson, R.K. (1978). Erratum: Sound scattering from a fluid sphere revisited. The Journal of the Acoustical Society of America, 63: 626.

Stanton, T.K. (1989). Simple approximate formulas for backscattering of sound by spherical and elongated objects. The Journal of the Acoustical Society of America, 86: 1499-1510.

Examples

subset(available_models(), model == "hpa")

Kirchhoff Ray Mode (KRM) scattering model

Description

Computes the far-field acoustic scattering amplitude and derived quantities for fish and similar elongated scatterers using the Kirchhoff-Ray Mode (KRM) approximation described by Clay and Horne (1994). The KRM model is widely used in fisheries acoustics for estimating target strength, particularly for fish with gas-filled swimbladders.

The model represents the fish body and swimbladder as a series of contiguous cylindrical elements and computes the coherent sum of their scattered fields. Depending on frequency and element size, scattering from each segment is evaluated using either a low-frequency modal solution or a high-frequency Kirchhoff (ray-based) approximation.

Value

No value; this help topic documents the KRM model.

Usage

This model is accessed via:

target_strength(
  ...,
  model="krm",
  sound_speed_sw,
  density_sw,
  krm_variant = "lowcontrast"
)

Arguments

sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
krm_variant: Swimbladder-medium convention for combined body-plus-bladder targets. Use "lowcontrast" for the low-contrast approximation k_B \approx k in both swimbladder regimes, "body_embedded" for the literal body-embedded interpretation of Clay and Horne (1994), or "mixed" for the intermediate convention in which the high-ka swimbladder term uses the body medium but the low-ka breathing-mode term uses the low-contrast approximation. This argument is ignored for fluid-only body targets.

Scatterer representation

The scatterer must provide body and swimbladder geometry discretized into axial segments. Each segment is described by its longitudinal position and cross-sectional dimensions. Typical geometric quantities include x(j), z_U(j), z_L(j), and radius a(j) for both the body and the swimbladder.

The incident plane wave is defined by angle \theta, and coordinates are transformed into a rotated system according to:

u(j) = x(j) \sin \theta - z(j) \cos \theta,

v(j) = x(j) \cos \theta + z(j) \sin \theta,

\Delta u_j = [x(j+1) - x(j)] \sin \theta,

a_j = [w(j) + w(j+1)] / 4.

Segment lengths and effective radii are computed from adjacent points and used to evaluate the scattering contribution from each element.

Theory

The total backscattering amplitude is computed as the coherent sum of all scatterer segments:

\mathcal{L} = \sum\limits_{b=1}^{N_b} \mathcal{L}_{B,b} + \sum\limits_{s=1}^{N_s} \mathcal{L}_{SB,s},

where \mathcal{L}_{B,b} is the contribution from the b-th body segment and \mathcal{L}_{SB,s} is from the s-th swimbladder segment. For body segments:

\mathcal{L}_{B,b} \approx -i \frac{\mathcal{R}_{wb}}{2\sqrt{\pi}} (k a_b)^{1/2} \Delta u_b \left[ e^{-i2k v_{U,b}} - \mathcal{T}_{wb}\mathcal{T}_{bw} e^{-i2k v_{U,b} + i 2 k_B (v_{U,b} - v_{L,b}) + i \psi_{B,b}} \right],

where \mathcal{R}_{wb} and \mathcal{T}_{wb} are reflection and transmission coefficients at the water-body interface, k is the wavenumber in water, and k_B in the body. The quantities v_{U,b} and v_{L,b} are the rotated upper- and lower-surface coordinates of the b-th segment, \Delta u_b = [x(b+1)-x(b)] \sin\theta, and \psi_{B,b} is an empirical phase correction.

The scattering from the swimbladder depends on the dimensionless frequency parameter ka_e, a_e is the equivalent swimbladder radius. For low frequencies (ka < 0.15), the swimbladder is treated as a finite-length gas-filled cylinder, and the scattering is dominated by the first cylindrical mode (breathing mode):

L_M(ka)|_{m=0} = e^{i(\chi - \pi/4)} \frac{L_e}{\pi} \frac{\sin \Delta}{\Delta} b_0,

b_0 = -\frac{1}{1 + i C_0},

where C_0 is a mode coefficient determined by the material properties and boundary conditions of the swimbladder. For higher frequencies ka \ge 0.15), the Kirchhoff-ray approximation is used:

\mathcal{L}_{SB,s} \approx -i \frac{\mathcal{R}_{bc} \mathcal{T}_{wb}\mathcal{T}_{bw}}{2\sqrt{\pi}} A_{SB,s} [(k a_s + 1)\sin\theta]^{1/2} \Delta u_s e^{-i (2 k_B v_s + \psi_{p,s})}.

Here, a_s and v_s are the averaged radius and longitudinal position for the segment, \mathcal{R}_{bc} is the reflection coefficient at the body-cylinder interface, and A_{SB,s} and \psi_{p,s} are empirical amplitude and phase adjustments, respectively.

For body-plus-swimbladder targets, the default coherent KRM combines the two complex scattering lengths as:

f_{bs}^{(\mathrm{coh})} = f_{body} + f_{bladder},

which gives:

\sigma_{bs}^{(\mathrm{coh})} = \left|f_{body} + f_{bladder}\right|^2.

Swimbladder medium conventions

Clay and Horne (1994) derive the swimbladder term for a gas-filled inclusion embedded in body tissue, but also note that the low body-water contrast can justify the approximation k_B \approx k. For combined body-plus- bladder targets, acousticTS exposes that choice through krm_variant:

"body_embedded": Use the body medium for both the high-ka Kirchhoff swimbladder term and the low-ka breathing-mode term. This is the most literal interpretation of the body-embedded swimbladder geometry in Clay and Horne (1994).
"mixed": Use the body medium for the high-ka swimbladder term but the water approximation for the low-ka breathing-mode term. This follows the later mixed convention discussed in the fisheries-acoustics literature.
"lowcontrast": Use the low-contrast approximation k_B \approx k for both swimbladder regimes, i.e. evaluate both the high-ka and low-ka swimbladder terms with the external-medium wavenumber rather than the body-medium wavenumber.

These named variants make the swimbladder-medium assumption explicit while keeping the public API tied to the scientific interpretation rather than to implementation-specific knob names.

Assumptions and limitations

The KRM formulation assumes that the scatterer is smooth, elongated, and approximately axisymmetric, such that both the Kirchhoff (ray) approximation and low-order cylindrical mode solutions are valid representations of the local scattering physics. The body andswimbladder are discretized into short axial segments, each with its own local height and width. While the segments are treated as locally cylindrical for the purpose of computing the scattered field, their dimensions may vary independently along the body axis. The total scattered field is obtained as a coherent sum of the contributions from these segments, which implicitly assumes that geometric and material properties vary gradually relative to the acoustic wavelength.

The model further assumes that scattering is dominated by first-order interactions between the incident field and each local element. Multiple internal reflections and higher-order multiple scattering between different segments are neglected. For the fish body, the material is treated as fluid-like, with no explicit treatment of elastic shear waves or bending modes. As a result, elastic shell effects, bone resonance, and complex internal structural scattering are not represented explicitly, except insofar as they may be approximated through effective reflection or transmission coefficients.

The Kirchhoff approximation employed in the high-frequency regime assumes that the local radius of curvature of each segment is large compared to the acoustic wavelength, and that the incident wave interacts primarily with the illuminated surface. Accuracy degrades for end-on incidence, sharp geometric discontinuities, or highly concave regions, where shadowing and diffraction effects become significant. The low-frequency mode solution used for small values of ka is limited to the lowest-order cylindrical modes and does not capture higher-order resonances that may arise for more complex internal geometries.

Orientation dependence is treated deterministically through the incident angle \theta, and the model does not account for stochastic body deformations, posture changes, or dynamic swimbladder shape variations. Surface roughness may be included through empirical attenuation of the reflection coefficient, but this treatment is phenomenological and does not represent scattering from discrete roughness elements. Consequently, the KRM is best suited for predicting mean or orientation-specific target strength for smooth-bodied organisms, and its accuracy decreases when applied to organisms with highly irregular shapes, strong elastic contrasts, or complex internal skeletal structures.

Fluid-only and alternative scattering configurations

Although the KRM formulation is most commonly applied to fish with gas-filled swimbladders, the model can also be used to compute target strength using only the fluid-like scattering contribution of the body.

In this configuration, the swimbladder scattering term is omitted and the total scattered field is obtained solely from the fluid contrast between the animal body and the surrounding medium. This mode of operation is appropriate for organisms that lack swimbladders (e.g. many invertebrates, elasmobranchs, or larval fish), or when swimbladder geometry is unknown or intentionally excluded.

More generally, the swimbladder component in the KRM framework may be replaced or supplemented by alternative internal scattering features, provided they can be represented geometrically and assigned appropriate acoustic boundary conditions. Examples include rigid or elastic skeletal structures (e.g. vertebral columns) or other localized impedance contrasts within an otherwise fluid-like body.

In all cases, the total target strength is computed from the coherent sum of the selected scattering components. Users are responsible for ensuring that the assumed boundary conditions and material contrasts are consistent with the biological structure being modeled.

Implementation

The implementation extracts geometric and acoustic parameters from the input object, transforms coordinates to the rotated reference frame, evaluates the appropriate modal or ray-based scattering expression for each segment, and coherently sums the contributions to obtain the total scattering amplitude and target strength.

References

Clay, C.S. (1991). Low resolution acoustic scattering models: Fluid-filled cylinders and fish with swimbladders. The Journal of the Acoustical Society of America, 89: 2168-2179.

Clay, C.S. (1992). Composite ray-mode approximations for backscattered sound from gas-filled cylinders and swimbladders.The Journal of the Acoustical Society of America, 92: 2173-2180.

Clay, C.S., and Horne, J.K. (1994). Acoustic models of fish: The Atlantic cod (Gadus morhua). The Journal of the Acoustical Society of America, 96: 1661-1668.

Examples

subset(available_models(), model == "krm")

Oblate spheroidal body shape

Description

Oblate spheroidal body shape

Value

An object of the OblateSpheroid S4 class.

Examples

methods::getClass("OblateSpheroid")

Phase-compensated distorted wave Born approximation (PCDWBA)

Description

Computes backscatter from weakly scattering elongated fluid-like targets using the phase-compensated distorted wave Born approximation (PCDWBA) described by Chu and Ye (1999). This model is particularly suited to uniformly bent or gently curved cylindrical bodies with tapered ends, but it can also operate on arbitrary fluid-like centerline profiles stored in FLS objects.

Value

No value; this help topic documents the PCDWBA model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "PCDWBA",
  sound_speed_sw,
  density_sw,
  radius_curvature,
  radius_curvature_ratio
)

Arguments

sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
radius_curvature: Optional radius of curvature (m) used to rebuild a uniformly bent centerline for canonical cylinders.
radius_curvature_ratio: Optional radius of curvature divided by body length (\rho_c / L) used to rebuild a uniformly bent centerline for canonical cylinders.

References

Chu, D., and Ye, Z. (1999). A phase-compensated distorted wave Born approximation representation of the bistatic scattering by weakly scattering objects: Application to zooplankton. The Journal of the Acoustical Society of America, 106, 1732-1743.

Stanton, T.K. (1989). Sound scattering by cylinders of finite length. III. Deformed cylinders. The Journal of the Acoustical Society of America, 86, 691-705.

Examples

subset(available_models(), model == "pcdwba")

Prolate spheroidal modal series (PSMS) solution

Description

Prolate spheroidal modal series (PSMS) solution

Details

Calculates the far-field scattering amplitude and related quantities for a prolate spheroid using the modal series solution, supporting various boundary conditions (rigid, pressure-release, liquid-filled, and gas-filled).

Value

No value; this help topic documents the PSMS model.

Usage

This model is accessed via:

target_strength(
  ...,
  model="psms",
  phi_body,
  boundary,
  adaptive,
  simplify_Amn,
  precision,
  n_integration,
  sound_speed_sw,
  density_sw
)

Arguments

phi_body: Incident roll angle (radians).
boundary: Boundary condition at the cylinder surface. One of "fixed_rigid", "pressure_release", "liquid_filled", or "gas_filled". See the boundary conditions documentation for more details on these different boundary conditions.
adaptive: A boolean argument controlling whether the PSMS backend is allowed to stop once the retained modal tail becomes numerically negligible and to choose an adaptive quadrature order for full fluid- or gas-filled overlap integrals. When FALSE (default), the implementation uses the published hard truncation rule and a fixed quadrature order unless the user overrides it directly. When TRUE, the hard m_{\max} and n_{\max} rules remain the upper bounds, but the backscatter implementation is allowed to stop early once the retained tail is both numerically small and gradient-flat.
simplify_Amn: A boolean argument that flags whether or not to use the simplified calculation for the exansion matrix, A_{mn}, for a fluid-filled scatterer. See Theory for the mathematical formulation and assumptions. Note: this argument only applies to when boundary = "liquid_filled" or boundary = "gas_filled". It is otherwise left unused for all other boundary conditions.
precision: A literal argument that allows for levels of precision when calculating the expansion matrix, A_{mn}. There are two choices: "double" for double-precision (64-bit) and "quad" for quadruple-precision (128-bit). See Details for more double- and quadruple-precision usages are implemented.
n_integration: An integer argument that informs the model how many integration points will be used to calculate \alpha_{mn}^{m}, which is numerically calculated using Gauss-Legendre quadrature. When left as NULL, the model uses 96 integration points unless adaptive = TRUE, in which case a reduced-frequency-based quadrature rule is selected internally for the full liquid-filled solve. See gauss_legendre for a full description of how n_integration is used. Note: this argument only applies to when boundary = "liquid_filled" or boundary = "gas_filled". It is otherwise left unused for all other boundary conditions.
sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).

Theory

some relevant parameters are used to describe the geometry. A spheroid surface is given by \xi = \xi_0 = \mathrm{constant}. Denoting the major radius a, the minor radius b, and the semi-focal-length q, then:

a = \xi_0 q \\ \xi_0 = \left[1 - \left(\frac{b}{a}\right)^2\right]^{-1/2}

Densities are expressed by \rho, sound speeds by c, and wavenumbers by k, each followed by a subscript 0 for the surrounding medium or 1 for the spheroidal body. For the spheroid, an alternative of the reduced frequency ka is h = kq.

The far-field scattering amplitude is given by:

f_\infty(\theta, \phi | \theta', \phi') = \frac{2}{j k_0} \sum\limits_{m=0}^\infty \sum\limits_{n=m}^\infty \frac{\epsilon_m}{N_{mn}(h_0)} S_{mn}(h_0, \cos\theta') \, A_{mn} S_{mn}(h_0, \cos\theta) \cos m(\phi - \phi')

where \epsilon_m = (-1)^{m/2} for even m, and N_{mn}(h_0) is the norm. S_{mn} is the angle spheroidal wave function of the first kind of order m and degree n, and A_{mn} is the expansion coefficient for the scattered wave, determined by the boundary conditions. The parameters \theta and \phi denote the spherical angle coordinates of an observed point along the body. The \theta' and \phi' denote similar spherical angle coordinates of the incident direction. Effectively, \phi and \theta correspond to the roll and tilt angles (relative the incident sound wave), respectively. It is assumed that \theta' and \phi' are perpendicular to the incident wave such that:

\theta' = \pi - \theta \\ \phi' = \pi + \phi

For pressure release (or soft) and rigid spheroids:

A_{mn} = \frac{-\Delta R_{mn}^{(1)}(h_0, \xi_0)}{ \Delta R_{mn}^{(3)}(h_0, \xi_0) }

where \Delta = 1 for soft and \Delta = \partial / \partial \xi f or rigid spheroid, and R_{mn}^{(i)} is the radial spheroidal wave function of the i-th kind.

For the case of a fluid-filled spheroid, the following simultaneous equation must be solved:

\sum\limits_{n'=m}^\infty K_{nn'}^{(3)} A_{mn'} + \sum\limits_{n'=m}^\infty K_{nn'}^{(1)} \alpha_{mn'}^{m} E_{n'}^{m(1)} = 0

where

K_{nl}^{(i)} = \frac{1}{N_{mn}(h_0)} \int\limits_{-1}^{1} S_{mn}(h_0, \cos\theta) S_{ml}(h_1, \eta) d\eta

and

\alpha_{mn}^{m} = \frac{1}{N_{mn}(h_1)} \int\limits_{-1}^{1} S_{mn}(h_0, \eta) S_{mn}(h_1, \eta) d\eta

In practice, these kernel matrices are solved numerically to determine A_{mn}. The implementation uses compiled dense linear algebra and keeps the fluid-filled solve in the requested arithmetic so that the linear-system stage does not become detached from the rest of the chosen precision pathway.

In the case that h_0 \approx h_1, \alpha_{mn}^{m} \approx 0 for n \neq l, and a much simplified expression is derived:

A_{mn} = -\frac{E_{mn}^{m(1)}}{E_{mn}^{m(3)}}

The maximum values of m and n can be estimated by:

m_{\max} = [2 k_0 b] \\ n_{\max} = m_{\max} + [h_0 / 2]

Implementation

C++

This model is primarily implemented in C++ since it leverages the Fortran algorithm developed by Arnie Lee van Buren and Jeffery Boisvert. Another reason this is primarily written in C++ is due to computational and performance reasons. As k_0, b, and h increase, so do m_{\max} and n_{\max}. While this is not as much of a concern for the pressure-release and fixed rigid cases, this results in increasingly large and unwieldy kernel matrices required for solving the fluid-filled expansion matrices (A_{mn}). Consequently, this can result in the model taking an impractical amount of time to compute f_\infty(\theta, \phi | \theta', \phi'). C++ helps reduce this burden compared to a pure R implementation. The current implementation uses compiled matrix algebra throughout, applies backscatter parity to avoid recomputing one of the two angular S_{mn} matrices, and solves the fluid-filled kernel system natively in the requested arithmetic.

Precision

Another consideration is the floating point precision inherent to R. R uses double-precision, which stores numeric values in a 64-bit format. At low m_{\max} and n_{\max}, there is lower numerical instability in the prolate spheroidal wave functions used in the model. However, this is not the case at greater m_{\max} and n_{\max} where the difference between double- (64-bit) and quadruple-precision (128-bit) can contribute to differences in target strength of more than 1 dB. While R-packages like Rmpfr provide access to the (GNU) MPFR C library, the (GCC) libquadmath C++ library. Quad precision nevertheless remains much more computationally intensive than double precision because the spheroidal function evaluations, overlap integrals, and kernel systems all grow rapidly with m_{\max} and n_{\max}.

References

Furusawa, M. (1988). Prolate spheroidal models for predicting general trends of fish target strength. Journal of the Acoustical Society of Japan, 9: 13-24.

Sanderson, C., and Curtin, R. (2019). Practical sparse matrices in C++ with hybrid storage and template-based expression optimisation. Mathematical and Computational Applications, 24: 70.

Spencer, R.D., and Granger, S. (1951). The scattering of sound from a prolate spheroid. The Journal of the Acoustical Society of America, 23: 701-706.

Van Buren, A. L. and Boisvert, J. E. "Prolate Spheroidal Wave Functions." GitHub repository: https://github.com/MathieuandSpheroidalWaveFunctions/Prolate_swf

Examples

subset(available_models(), model == "psms")

Legendre Polynomial of the First Kind, `P_\nu(x)`

Description

Computes the Legendre polynomial of the first kind, P_\nu(x), for real order \nu (integer or fractional) and real argument x.

Usage

Pn(n, x)

Arguments

n

Numeric vector. Degree (order) of the Legendre polynomial. Can be integer or fractional (e.g., 0, 1, 2.5, 3.7). Can also be negative.

x

Numeric vector. Real argument(s) at which to evaluate the polynomial. Valid for all real values including |x| > 1.

Details

The Legendre polynomial of the first kind satisfies the differential equation:

(1 - x^2) \frac{d^2 P_\nu}{dx^2} - 2x \frac{dP_\nu}{dx} + \nu(\nu + 1) P_\nu = 0

For integer order n, the function uses the recurrence relation:

P_0(x) = 1

P_1(x) = x

P_n(x) = \frac{(2n-1) x P_{n-1}(x) - (n-1) P_{n-2}(x)}{n}

For fractional order \nu, the function uses:

For |x| \leq 1: The Ferrers function via the hypergeometric series P_\nu(x) = {}_2F_1(-\nu, \nu+1; 1; \frac{1-x}{2})
For |x| > 1: A numerical contour integral representation

Value

A numeric matrix of dimension length(n) by length(x), where element [i, j] contains P_{n_i}(x_j).

Note

This function calls underlying C++ code via Rcpp for computational efficiency and to support different cases for both order and argument that are not readily available in R.

References

Abramowitz, M. and Stegun, I. A. (1972). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. Dover Publications. Chapter 8: Legendre Functions.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/14

Examples

# Single values
Pn(1, 1)

# Multiple orders, single argument
Pn(c(1, 2, 3), 1)

# Single order, multiple arguments
Pn(1, c(1, 2, 3))

# Multiple orders and arguments (returns a matrix)
Pn(c(1, 2, 3), c(1, 2, 3))

# Fractional orders
Pn(c(0.5, 2.2, 3), c(1, 2, 3))

# Negative arguments
Pn(c(0.5, 2, -3), c(1, -2.5, 3))

Derivative of the Legendre Polynomial of the First Kind

Description

Computes the k-th derivative of the Legendre polynomial of the first kind, \frac{d^k}{dx^k} P_\nu(x), with respect to the argument x.

Usage

Pndk(n, x, k = 1L)

Arguments

n

Numeric vector. Degree (order) of the Legendre polynomial. Can be integer or fractional.

x

Numeric vector. Real argument(s) at which to evaluate the derivative.

k

Integer. Order of the derivative (k \geq 0). Default is 1 for the first derivative.

Details

For integer order n:

The derivative is computed using the relationship with associated Legendre polynomials:

\frac{d^m P_n(x)}{dx^m} = \frac{1}{(1-x^2)^{m/2}} P_n^m(x)

where P_n^m(x) is the associated Legendre polynomial (the Boost C++ uses Condon-Shortley phase convention).

At the endpoints x = \pm 1, the known closed-form expressions are used:

P_n^{(k)}(1) = \frac{1}{2^k k!} \prod_{j=0}^{k-1} (n-j)(n+1+j)

P_n^{(k)}(-1) = (-1)^{n+k} P_n^{(k)}(1)

If k > n for integer n, the result is 0 (derivative of a polynomial of degree n taken more than n times).

For fractional order \nu:

Derivatives are computed using central finite differences:

\frac{dP_\nu}{dx} \approx \frac{P_\nu(x+h) - P_\nu(x-h)}{2h}

Higher-order derivatives use the generalized finite difference stencil. Note that accuracy may be limited for fractional orders due to the numerical integration underlying Pn.

Value

A numeric matrix of dimension length(n) by length(x), where element [i, j] contains \frac{d^k}{dx^k} P_{n_i}(x_j).

Note

For fractional orders, the finite difference approximation may have reduced accuracy (typically 4-6 significant digits) compared to integer orders. A warning is issued for higher-order derivatives (k > 1) of fractional orders.

This function calls underlying C++ code via Rcpp for computational efficiency and to support different cases for both order and argument that are not readily available in R.

References

Abramowitz, M. and Stegun, I. A. (1972). Handbook of Mathematical Functions. Dover Publications. Section 8.5: Associated Legendre Functions.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/14.10

Examples

# First derivative of P_2(x) at x = 0.5
# P_2(x) = (3x^2 - 1)/2, so P'_2(x) = 3x, P'_2(0.5) = 1.5
Pndk(2, 0.5, 1)

# Second derivative of P_2(x)
# P''_2(x) = 3
Pndk(2, 0.5, 2)

# Multiple orders
Pndk(c(1, 2, 3), 0.5, 1)

# First derivative at multiple points
Pndk(2, c(-0.5, 0, 0.5), 1)

# Fractional order (uses finite differences)
Pndk(0.5, 0.5, 1)

# Derivative at endpoint
# P'_n(1) = n(n+1)/2
Pndk(3, 1, 1)  # Should be 3*4/2 = 6

Cylindrical body shape deformed using a polynomial

Description

Cylindrical body shape deformed using a polynomial

Value

An object of the PolynomialCylinder S4 class.

Examples

methods::getClass("PolynomialCylinder")

Prolate spheroidal body shape

Description

Prolate spheroidal body shape

Value

An object of the ProlateSpheroid S4 class.

Examples

methods::getClass("ProlateSpheroid")

Legendre Function of the Second Kind, `Q_\nu(x)`

Description

Computes the Legendre function of the second kind, Q_\nu(x), for real order \nu (integer or fractional) and real argument x. Returns complex values when |x| > 1.

Usage

Qn(n, x)

Arguments

n

Numeric vector. Degree (order) of the Legendre function. Can be integer or fractional (e.g., 0, 1, 2.5, 3.7).

x

Numeric vector. Real argument(s) at which to evaluate the function. Valid for all real values. Note that x = \pm 1 are singularities.

Details

The Legendre function of the second kind satisfies the same differential equation as P_\nu(x):

(1 - x^2) \frac{d^2 Q_\nu}{dx^2} - 2x \frac{dQ_\nu}{dx} + \nu(\nu + 1) Q_\nu = 0

but represents the linearly independent second solution.

For |x| < 1 (real result):

For integer order n: Uses the C++ Boost library implementation
For fractional order \nu: Uses the Ferrers identity

Q_\nu(x) = \frac{\pi}{2 \sin(\pi \nu)} \left[ \cos(\pi \nu) P_\nu(x) - P_\nu(-x) \right]

For x = \pm 1: Returns infinity (singularity).

For |x| > 1 (complex result):

Real part: Computed via the integral representation

\text{Re}[Q_\nu(x)] = \int_0^\infty \frac{dt}{(x + \sqrt{x^2-1} \cosh t)^{\nu+1}}
Imaginary part:

\text{Im}[Q_\nu(x)] = -\frac{\pi}{2} P_\nu(x)

Value

A complex matrix of dimension length(n) by length(x), where element [i, j] contains Q_{n_i}(x_j). For |x| < 1, the imaginary part is zero.

Note

This function calls underlying C++ code via Rcpp for computational efficiency and to support different cases for both order and argument that are not readily available in R.

References

Abramowitz, M. and Stegun, I. A. (1972). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. Dover Publications. Chapter 8: Legendre Functions.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/14

Examples

# Single values
Qn(1, 0.5)

# Multiple orders, single argument
Qn(c(1, 2, 3), 0.5)

# Single order, multiple arguments
Qn(1, c(-0.5, 0, 0.5))

# Multiple orders and arguments (returns a matrix)
Qn(c(1, 2, 3), c(0.25, 0.5, 0.75))

# Fractional orders
Qn(c(0.5, 1.5, 2.7), c(0.5, 0.9))

# Arguments |x| > 1 return complex values
Qn(c(1, 2, 3.5), c(2, 3.5))

# Singularity at x = 1
Qn(1, 1)

Derivative of the Legendre function of the second kind

Description

Derivative of the Legendre function of the second kind

Usage

Qndk(n, x, k = 1L)

Arguments

n

Numeric vector. Degree (order) of the Legendre function.

x

Numeric vector. Real argument(s) at which to evaluate the derivative. Avoid x = \pm 1.

k

Integer. Order of the derivative (k \geq 0). Default is 1.

Value

A complex matrix of dimension length(n) by length(x), where element [i, j] contains \frac{d^k}{dx^k} Q_{n_i}(x_j).

Note

Derivatives are computed via finite differences with step size h = 10^{-6}. Accuracy is typically 4-6 significant digits for first derivatives, less for higher orders.

This function calls underlying C++ code via Rcpp for computational efficiency and to support different cases for both order and argument that are not readily available in R.

References

Abramowitz, M. and Stegun, I. A. (1972). Handbook of Mathematical Functions. Dover Publications. Chapter 8: Legendre Functions.

Examples

# First derivative of Q_1(x) at x = 0.5
Qndk(1, 0.5, 1)

# Compare with numerical derivative
h <- 1e-6
(Qn(1, 0.5 + h) - Qn(1, 0.5 - h)) / (2 * h)

# Second derivative
Qndk(2, 0.5, 2)

# Multiple orders
Qndk(c(1, 2, 3), 0.5, 1)

# Complex result for |x| > 1
Qndk(1, 2.0, 1)

Prolate Spheroidal Radial Functions

Description

Computes the prolate spheroidal radial functions of the first (R_{mn}^{(1)}), second (R_{mn}^{(2)}), third (R_{mn}^{(3)}), and fourth (R_{mn}^{(4)}) kinds and their first derivatives with respect to \xi for given order m, degree n, size parameter c, and radial coordinate \xi.

This function is an R wrapper for compiled C++ code, which in turn calls the underlying Fortran library (prolate_swf) for high-performance numerical computation. All heavy computation is performed in compiled code for speed and accuracy.

Usage

Rmn(m, n, c, xi, kind = 1, precision = "double")

Arguments

m

Non-negative integer. The order of the spheroidal function (m \geq 0).

n

Non-negative integer. The degree of the spheroidal function (n \geq m).

c

Numeric. The scalar size parameter (also denoted \gamma in some references).

xi

Numeric. The radial coordinate at which to evaluate the function. Must satisfy \xi \geq 1.

kind

Integer. Specifies which kind of radial function to compute: 1 (first kind), 2 (second kind), 3 (third kind/outgoing), or 4 (fourth kind/incoming). Default is 1.

precision

Character. Either "double" (default) or "quad". Controls the floating-point precision used in the underlying Fortran computation.

"double": Uses standard double-precision (64-bit) arithmetic. Fastest and sufficient for most applications.
"quad": Uses quadruple-precision (128-bit) arithmetic for higher numerical accuracy in challenging parameter regimes (e.g., large m, n, c, or near singularities). Computation is significantly slower and requires a package build with native quad precision support.

Details

The prolate spheroidal radial functions are solutions to the radial part of the scalar Helmholtz equation in prolate spheroidal coordinates. They satisfy the differential equation:

(\xi^2 - 1) \frac{d^2 R_{mn}}{d\xi^2} + 2\xi \frac{dR_{mn}}{d\xi} - \left(\lambda_{mn} - c^2 \xi^2 + \frac{m^2}{\xi^2 - 1}\right) R_{mn} = 0

where \lambda_{mn} is the separation constant (eigenvalue).

Function kinds:

kind = 1: Radial function of the first kind R_{mn}^{(1)}(c, \xi). Regular at the origin; analogous to spherical Bessel functions j_n.
kind = 2: Radial function of the second kind R_{mn}^{(2)}(c, \xi). Singular at the focal points (\xi = 1); analogous to spherical Neumann functions y_n.
kind = 3: Radial function of the third kind (outgoing Hankel-type) R_{mn}^{(3)}(c, \xi) = R_{mn}^{(1)}(c, \xi) + i R_{mn}^{(2)}(c, \xi). Used for outgoing wave solutions.
kind = 4: Radial function of the fourth kind (incoming Hankel-type) R_{mn}^{(4)}(c, \xi) = R_{mn}^{(1)}(c, \xi) - i R_{mn}^{(2)}(c, \xi). Used for incoming wave solutions.

Domain restrictions:

The radial coordinate must satisfy \xi \geq 1 (prolate domain).
The order must satisfy m \geq 0.
The degree must satisfy n \geq m.

Normalization: The functions use the Morse-Feshbach normalization by default, where the radial functions reduce to spherical Bessel/Neumann functions as c \rightarrow 0.

Implementation: This function is an R wrapper for a compiled C++ interface (Rmn_cpp), which itself wraps the Fortran subroutine profcn from the prolate_swf library developed by Arnie Lee Van Buren and Jeffrey Boisvert. The underlying algorithm uses a combination of forward and backward recursion with the Bouwkamp eigenvalue method for high accuracy across wide parameter ranges. The C++ layer manages memory, precision selection, and data conversion between R and Fortran for robust and efficient computation.

Value

A list containing:

value: The function value R_{mn}^{(k)}(c, \xi). Real for kind = 1 or 2; complex for kind = 3 or 4.
derivative: The first derivative \frac{d}{d\xi}R_{mn}^{(k)}(c, \xi). Real for kind = 1 or 2; complex for kind = 3 or 4.

References

Van Buren, A. L. and Boisvert, J. E. "Prolate Spheroidal Wave Functions." GitHub repository: https://github.com/MathieuandSpheroidalWaveFunctions/prolate_swf

Morse, P. M. and Feshbach, H. (1953). Methods of Theoretical Physics. McGraw-Hill, New York. Chapter 21.

Flammer, C. (1957). Spheroidal Wave Functions. Stanford University Press.

NIST Digital Library of Mathematical Functions. Chapter 30: Spheroidal Wave Functions. https://dlmf.nist.gov/30

Examples

# First kind radial function
Rmn(m = 2, n = 3, c = 1, xi = 1.5, kind = 1)

# Second kind radial function
Rmn(m = 0, n = 2, c = 5, xi = 2.0, kind = 2)

# Third kind (outgoing) radial function
Rmn(m = 1, n = 1, c = 2, xi = 1.2, kind = 3)

# Fourth kind (incoming) radial function
Rmn(m = 1, n = 1, c = 2, xi = 1.2, kind = 4)

# Double precision (default)
Rmn(m = 2, n = 3, c = 1, xi = 1.5)

Swimbladdered fish (SBF) object/class.

Description

A S4 class that provides slots to contain relevant animal metadata for parameterizing models for swimbladdered fish (SBF) that are partitioned into two sets of discretized cylinders: the body and the swimbladder. Both shapes comprise independent position matrices, material properties, orientations, and other relevant shape-related data and metadata. See Scatterer for a more detailed description on how this S4 object is organized.

Value

An object of the SBF S4 class.

Examples

methods::getClass("SBF")

Stochastic distorted wave Born approximation (SDWBA) for weak scatterers

Description

Calculates the far-field scattering amplitude and related quantities for fluid-like, weak scatterers using the stochastic distorted wave Born approximation (SDWBA), as described by Demer and Conti (2003). The SDWBA extends the deterministic DWBA by incorporating stochastic phase variability to account for unresolved structural complexity and dynamic variability in biological scatterers.

Value

No value; this help topic documents the SDWBA model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "sdwba",
  n_iterations,
  n_segments_init,
  phase_sd_init,
  length_init,
  frequency_init,
  sound_speed_sw,
  density_sw
)

Arguments

n_iterations: Number of stochastic realizations for averaging target strength predictions.
n_segments_init: Reference number of body segments.
phase_sd_init: Reference phase deviation (radians).
length_init: Reference body length (m).
frequency_init: Reference frequency (Hz).
sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).

Theory

The SDWBA is derived under the weak scattering assumption, where the differences in compressibility (\kappa) and density (\rho) between the scatterer and the surrounding fluid are small enough to linearize the acoustic scattering problem (see DWBA). in this regime, multiple scattering within the body is neglected, and the total scattered field is approximated as the coherent sum of first-order contributions from individual body segments.

The key extension introduced by the SDWBA is the inclusion of stochastic phase variability to represent unresolved morphological complexity, internal inhomogeneity, and dynamic effects such as body flexure and orientation variability. The linear scattering coefficient is written as:

f_{bs}(\theta) = \sum\limits_{j=1}^N f_{bs}^{(j)}(\theta) \exp(i \varphi_j),

where N is the number of body segments, f_{bs}^{(j)} is the contribution from segment j, and \varphi_j is a random phase perturbation drawn independently for each segment.

The phase perturbations are assumed to follow a zero-mean Gaussian distribution with variance related to the effective signal-to-noise ratio (SNR) of the scattering process. The minimum expected phase variance due to noise is given by:

\mathbb{V}(\varphi_j) = \frac{1}{2 \mathrm{SNR}},

though in practice larger variances are used to account for additional physical sources of phase decorrelation not explicitly modeled.

The expected backscattering cross-section is obtained by ensemble averaging over multiple stochastic realizations:

\langle \sigma_{bs}(\theta) \rangle = \mathbb{E}\!\left[ \left| f_{bs}(\theta) \right|^2 \right] \approx \frac{1}{M} \sum_{m=1}^{M} \left| f_{bs}^{(m)}(\theta) \right|^2,

and the expected target strength, \mathbb{E}[TS(\theta)], is computed from this mean.

To ensure consistency across frequencies and body sizes, the SDWBA enforces scale invariance by preserving the product of the phase standard deviation, \mathrm{sd}_\varphi, and frequency, f:

\mathrm{sd}_{\varphi}(f)\, f = \mathrm{sd}_{\varphi_0}\, f_0,

and by scaling the number of segments to maintain constant spatial resolution relative to acoustic wavelength:

N(f, L) = N_0 \frac{f L}{f_0 L_0}.

The phase standard deviation at arbitrary frequency and length is then:

\mathrm{sd}_{\varphi}(f, L) = \mathrm{sd}_{\varphi_0} \frac{N_0 L}{N(f, L) L_0}.

These scaling relationships ensure that stochastic decorrelation effects remain physically consistent across different acoustic and geometric regimes.

Implementation

The implementation extracts geometric and acoustic parameters from the input object, constructs the required rotation and wavenumber matrices, and evaluates the DWBA contribution for each segment. For each stochastic realization, random phase perturbations are applied, and the resulting backscattering amplitudes are averaged over all realizations to estimate the expected target strength.

References

Conti, D.A., and Conti, S.G. (2006). Improved parameterization of the SDWBA for estimating krill target strength. ICES Journal of Marine Science, 63: 928-935.

Demer, D.A., and Conti, S.G. (2003). Reconciling theoretical versus empirical target strengths of krill: effects of phase variability on the distorted-wave Born approximation. ICES Journal of Marine Science, 60: 429-434.

Stanton, T.K., Chu, D., and Wiebe, P.H. (1998). Sound scattering by several zooplankton groups. II. Scattering models. The Journal of the Acoustical Society of America, 103, 236-253.

Examples

subset(available_models(), model == "sdwba")

Solid elastic (calibration) sphere modal series (SOEMS) solution

Description

Calculates the far-field scattering amplitude and related quantities for a solid elastic (calibration) sphere using a modal series solution.

Value

No value; this help topic documents the calibration model.

Usage

This model is accessed via:

target_strength(
  ...,
  model="calibration",
  sound_speed_sw,
  density_sw,
  adaptive = TRUE
)

Arguments

sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
adaptive: Logical. If TRUE, extend the partial-wave sum beyond the initial \mathrm{round}(ka)+10 modal cap until the tail term falls below the internal convergence threshold. If FALSE, use the original fixed modal cutoff only.

Theory

The calibration sphere model computes acoustic scattering from a solid elastic sphere by expanding the incident and scattered fields in terms of spherical Bessel and Hankel functions and Legendre polynomials. Both compressional and shear waves within the sphere are included, and the appropriate boundary conditions are enforced at the sphere-water interface.

The dimensionless frequency parameter is defined as q = ka, where k is the wavenumber in water and a is the sphere radius. The longitudinal and transverse wave numbers inside the sphere are

q_1 = \frac{qc}{c_1} \\ q_2 = \frac{qc}{c_2},

where c_1 and c_2 are the longitudinal and transverse sound speeds in the sphere, respectively.

The far-field backscattering form function is given by:

f_\infty(q) = -\frac{2}{q} \sum\limits_{\ell=0}^{\infty} (-1)^\ell (2\ell+1) \sin \eta_\ell \exp(i \eta_\ell)

The phase angle for each mode is then given by:

\tan \eta_\ell = -\frac{B_2 j_\ell'(q) - B_1 j_\ell(q)}{B_2 y_\ell'(q) - B_1 y_\ell(q)}

where the phase angle \eta_\ell is determined by the boundary conditions and the material properties of the sphere and surrounding fluid. The phase angle \eta_\ell is calculated using a series of coefficients. The auxilliary quantities used for determining the boundary conditions and subsequently \eta_\ell are reported in MacLennan (1981).

References

Hickling, R. (1962). Analysis of echoes from a solid elastic sphere in water. The Journal of the Acoustical Society of America, 34: 1582-1592.

MacLennan D. N. (1981). The theory of solid spheres as sonar calibration targets. Scottish Fisheries Research No. 22, Department of Agriculture and Fisheries for Scotland.

Examples

subset(available_models(), model == "calibration")

Spherical modal series (SPHMS) solution

Description

Spherical modal series (SPHMS) backscatter model. Supports rigid, pressure-release, fluid-filled, shelled (pressure-release/liquid/gas). Frequencies in Hz; sound speed in m/s; density in kg/m^3. Material properties may be contrasts or absolute (contrasts derived relative to seawater). Full equations and boundary-condition details are documented in the SPHMS vignette.

Value

No value; this help topic documents the SPHMS model.

Usage

This model is accessed via:

target_strength(
  ...,
  model="sphms",
  boundary,
  sound_speed_sw,
  density_sw,
  m_limit
)

Arguments

boundary: Boundary condition at a spherical surface. One of "fixed_rigid", "pressure_release", "liquid_filled", "gas_filled", "shelled_pressure_release", "shelled_liquid", or "shelled_gas". See the boundary conditions documentation for more details on these different boundary conditions.
sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
m_limit: Optional model truncation limit used to cap the number of modes in the numerical calculation.

Theory

The modal series solution for a sphere expands backscatter from a spherical scatterer in spherical Bessel/Hankel modes. The form function is:

f_{bs} = -\frac{i}{k_w} \sum_{n=0}^{\infty} (-1)^n (2n+1) A_n,

References

Anderson, V.C. (1950). Sound scattering from a fluid sphere. The Journal of The Acoustical Society of America, 22: 426-431.

Examples

subset(available_models(), model == "sphms")

Scatterer-class object for target strength estimation

Description

The acousticTS package uses a variety of defined S4-class objects comprising different types of scatterers, such as fish with gas-filled swimbladders (SBF) and fluid-like crustaceans (FLS).

Value

An object from the Scatterer S4 class hierarchy.

Slots

metadata: List containing relevant metadata
model_parameters: Model parameters necessary for predicting TS

Data Organization

metadata:

A list comprising any identifying information associated with the scatterer. The default metadata entry includes ID that uses a default character value of "UID" (i.e. ID = "UID"). This can otherwise be formatted in any manner for book keeping purposes.

body/bladder:

A list that includes information relevant to the scatterer's position vector, material properties, tilt/orientation, etc. For some scatterers, this may only include body, but other targets may have an additional parameter such as bladder. Generally, each entry includes:

rpos: the relevant position vector (r₀) that includes axes such as x, y, z, etc., that depend on the type of scatterer being used.
radius: in some cases this includes the radius measurements for each cylinders depending on the type of scatterer object.
theta: the orientation of the scatterer relative to the transmitting transducer or sound source (θ_animal) that can be represented either by degrees or radians, although all functions require radians.
g, h: material properties that represent the density and sound speed contrasts (g and h, respectively) relative to the ambient/surrounding fluid. Some targets may instead have standard sound speed (c_animal, m s^-1) and density (ρ_animal, kg m³).

shape_parameters:

A list that includes metadata pertaining to the shape of the scatterer and any other features of interest (e.g. gas-filled swimbladder). Generally, each entry includes: overall body length, the number of discrete cylinders that make up the shape (if applicable), and the units related to both θ_animal (e.g. rad, °) and length (e.g. mm, m).

model_parameters:

A list that contains relevant model parameterization once an object has been initialized for modeling σ_bs. This is typically broken up into three categories:

parameters: A list that includes information such as frequency (Hz), acoustic wavenumber (i.e. k), etc.
medium: A data.frame including information such as the material properties of the ambient medium.
scatterer: A list containing summarized information used to parameterize certain scattering models.

model:

A list that collects model results from one or more models in the linear domain (i.e. σ_bs).

Supported Scatterers

Elastic-based scatterers (ELA)
Composite multi-component scatterers (CSC)
Backboned fish (BBF)
Calibration spheres (CAL)
Elastic-shelled scatterers (ESS)
Fluid-like scatterers (FLS)
Gas-filled scatterers (GAS)
Swimbladdered fish (SBF)

Examples

methods::getClass("Scatterer")

Generic scattering shape object used throughout this package.

Description

A S4 class that provides slots to contain relevant shape data and metadata for a variety of arbitrary and canonical shapes and geometries. See Scatterer for a more detailed description on how this S4 object interacts with generic Scatterer objects.

Value

An object from the Shape S4 class hierarchy.

Slots

position_matrix: Position matrix that provides the 2D representation of the body shape
shape_parameters: A list of additional shape specifications

Examples

methods::getClass("Shape")

Prolate Spheroidal Angular Function of the First Kind, `S^{1}_{mn}(c, \eta)`

Description

Computes the prolate spheroidal angular function of the first kind, S_{mn}^{(1)}(c, \eta), and its first derivative with respect to \eta for given order m, degree n, size parameter c, and angular coordinate \eta.

Usage

Smn(m, n, c, eta, normalize = FALSE, precision = "double")

Arguments

m

Non-negative integer. The order of the spheroidal function (m \geq 0).

n

Non-negative integer. The degree of the spheroidal function (n \geq m).

c

Numeric. The scalar size parameter.

eta

Numeric vector. The angular coordinate(s) at which to evaluate the function. Must satisfy |\eta| \leq 1.

normalize

Logical. If TRUE, the angular functions are normalized to have unity norm. If FALSE (default), the Meixner-Schäfke normalization is used.

precision

Character. Either "double" (default) or "quad". Controls the floating-point precision used in the underlying Fortran computation.

"double": Uses standard double-precision (64-bit) arithmetic. Fastest and sufficient for most applications.
"quad": Uses quadruple-precision (128-bit) arithmetic for higher numerical accuracy in challenging parameter regimes (e.g., large m, n, or near singularities). Computation is significantly slower and requires a package build with native quad precision support.

Details

The prolate spheroidal angular functions are solutions to the angular part of the scalar Helmholtz equation in prolate spheroidal coordinates. They satisfy the differential equation:

(1 - \eta^2) \frac{d^2 S_{mn}}{d\eta^2} - 2\eta \frac{dS_{mn}}{d\eta} + \left(\lambda_{mn} - c^2 \eta^2 + \frac{m^2}{1 - \eta^2}\right) S_{mn} = 0

where \lambda_{mn} is the separation constant (eigenvalue).

Domain restrictions:

The angular coordinate must satisfy |\eta| \leq 1.
The order must satisfy m \geq 0.
The degree must satisfy n \geq m.

Normalization: When normalize = FALSE (default), the functions use the Meixner-Schäfke normalization, which matches the normalization of the corresponding associated Legendre functions. When normalize = TRUE, the functions are scaled to have unity norm.

Implementation: This function is an R wrapper for a compiled C++ interface (Smn_cpp), which itself wraps the Fortran subroutine profcn from the prolate_swf library developed by Arnie Lee Van Buren and Jeffrey Boisvert. The underlying algorithm uses a combination of forward and backward recursion with the Bouwkamp eigenvalue method for high accuracy across wide parameter ranges. The C++ layer manages memory, precision selection, and data conversion between R and Fortran for robust and efficient computation.

Value

A list containing:

value: Numeric vector of function values S_{mn}^{(1)}(c, \eta) at each input eta.
derivative: Numeric vector of first derivatives \frac{d}{d\eta}S_{mn}^{(1)}(c, \eta) at each input eta.

References

Van Buren, A. L. and Boisvert, J. E. "Prolate Spheroidal Wave Functions." GitHub repository: https://github.com/MathieuandSpheroidalWaveFunctions/prolate_swf

Meixner, J. and Schäfke, F. W. (1954). Mathieusche Funktionen und Sphäroidfunktionen. Springer-Verlag, Berlin.

Flammer, C. (1957). Spheroidal Wave Functions. Stanford University Press.

NIST Digital Library of Mathematical Functions. Chapter 30: Spheroidal Wave Functions. https://dlmf.nist.gov/30

Examples

# Single evaluation
Smn(m = 2, n = 3, c = 1, eta = 0.5)

# Multiple eta values
Smn(m = 0, n = 2, c = 5, eta = c(-0.5, 0, 0.5))

# With unity normalization
Smn(m = 1, n = 1, c = 2, eta = 0.3, normalize = TRUE)

# Double precision (default)
Smn(m = 2, n = 3, c = 1, eta = 0.5, precision = "double")

Spherical body shape

Description

Spherical body shape

Value

An object of the Sphere S4 class.

Examples

methods::getClass("Sphere")

Single-target transition matrix method (TMM)

Description

Computes monostatic backscatter from a single axisymmetric target using a transition-matrix formulation. The current implementation targets smooth bodies of revolution and finite cylinders already represented in the package as a Sphere, OblateSpheroid, ProlateSpheroid, or Cylinder, and supports rigid, pressure-release, and homogeneous penetrable fluid/gas interiors.

Details

This implementation is intentionally scoped to single targets. The default target_strength() result is monostatic backscatter, and retained T-matrix state can also be reused for angular post-processing where the active branch supports it.

For spheres and oblate spheroids, the current implementation uses a spherical-wave T-matrix: each retained azimuthal order is solved as an incident-to-outgoing modal coefficient map after projecting the boundary conditions on the target surface. For prolate spheroids, the implementation uses a geometry-matched spheroidal-basis T-matrix formulation, which is the natural coordinate system for that geometry and is consistent with the scalar spheroidal transition-matrix literature for single-target scattering. For finite cylinders, the default monostatic branch uses a cylindrical-coordinate modal T-matrix-style backend so that the backscatter benchmark remains aligned with the exact finite-cylinder family. When store_t_matrix = TRUE, cylinders retain lightweight cylindrical-family state that supports exact monostatic reuse and orientation-averaged monostatic products, while general-angle cylinder bistatic post-processing remains outside the current validated scope. Because of that narrower validation status, cylinder calls emit a warning by default; see options(acousticTS.warn_tmm_cylinder = FALSE) to silence it in controlled test or benchmarking workflows.

The sphere, oblate, prolate, and shell-sphere branches are therefore single-target acoustic T-matrix methods in the modal coefficient-map sense: they represent the target response as a map from incident modal amplitudes to scattered modal amplitudes and reuse that retained state for supported post-processing. The cylinder branch is more limited and should be treated as a guarded monostatic modal T-matrix-style branch until a validated general-angle cylindrical operator is available.

Value

No value; this help topic documents the TMM model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "TMM",
  boundary,
  sound_speed_sw,
  density_sw,
  n_max,
  store_t_matrix
)

Arguments

boundary: Boundary condition at the target surface. One of "fixed_rigid", "pressure_release", "liquid_filled", or "gas_filled".
sound_speed_sw: Surrounding-medium sound speed (m~s^{-1}).
density_sw: Surrounding-medium density (kg~m^{-3}).
n_max: Optional truncation limit. For spheres and oblate spheroids, this is the maximum spherical-wave degree used in the truncated T-matrix solve. For the default monostatic cylinder branch, it is the cylindrical modal cutoff used in the geometry-matched backend. When left as NULL, a geometry-aware rule is used frequency-by-frequency. This argument is currently ignored for prolate spheroids, which use the spheroidal-coordinate branch.
store_t_matrix: Logical flag controlling whether the frequency-specific retained state is stored under object@model_parameters$TMM$parameters$t_matrix. The default is FALSE to avoid large object sizes. Explicit block retention is available for the spherical and spheroidal branches. For cylinders, the stored state keeps the geometry-matched cylindrical monostatic family available for exact monostatic reuse and orientation-averaged monostatic products; full general-angle cylinder bistatic post-processing is not yet provided.

Theory

For a single target, the incident and scattered fields are expanded in regular and outgoing modal bases, respectively:

p^{inc} = \sum_{\nu} a_{\nu} \, \psi_{\nu}^{(1)}, \qquad p^{sca} = \sum_{\nu} f_{\nu} \, \psi_{\nu}^{(3)},

where the transition matrix \mathbf{T} maps incident coefficients to scattered coefficients:

\mathbf{f} = \mathbf{T}\mathbf{a}.

For the axisymmetric single-target case used here, the azimuthal orders decouple. Each retained block is recovered in the basis used by the active geometry branch: spherical for spheres and oblates, spheroidal for prolates, and exact spherical modal coefficients for supported shell spheres. The backscatter amplitude is obtained by evaluating the outgoing expansion in the monostatic receive direction opposite to the incident plane wave. When the retained state is stored, the same coefficient map can be reused for supported angular, bistatic, diagnostic, and orientation-averaged products.

References

Waterman, P. C. (1969). New formulation of acoustic scattering. The Journal of the Acoustical Society of America, 45, 1417-1429.

Varadan, V. K., Varadan, V. V., Bringi, V. N., and Waterman, P. C. (1982). Computation of rigid body scattering by prolate spheroids using the T-matrix approach. The Journal of the Acoustical Society of America, 71, 22-25.

Hackman, R. H. (1984). An application of the spheroidal-coordinate-based transition matrix: The acoustic scattering from high aspect ratio solids. The Journal of the Acoustical Society of America, 76, 1058-1070. Waterman, P. C. (2009). T-matrix methods in acoustic scattering. The Journal of the Acoustical Society of America, 125, 42-51.

Examples

subset(available_models(), model == "tmm")

Two-ray cylinder model (TRCM) for elongated scatterers

Description

Computes the far-field scattering amplitude and related quantities for elongated fluid-like scatterers using the two-ray approximation model, as described by Stanton et al. (1993, 1998). The two-ray model is a high-frequency ray-based approximation that accounts for interference between reflections from the front and back interfaces of the scatterer, along with a directivity pattern that depends on the scatterer's orientation and curvature. The model is computationally efficient and captures the essential physics of acoustic scattering from elongated bodies such as zooplankton, particularly at high frequencies where the acoustic wavelength is much smaller than the organism size. The model supports both straight and bent cylinders, with the bent cylinder formulation incorporating the radius of curvature to account for body shape effects on the directivity pattern. For a fuller derivation and implementation discussion, see vignette("trcm-theory", package = "acousticTS").

Value

No value; this help topic documents the TRCM model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "TRCM",
  radius_curvature,
  radius_curvature_ratio,
  radius_cylinder_fun,
  sound_speed_sw,
  density_sw
)

Arguments

radius_curvature: Radius of curvature for bent cylinders (m). If NULL, the model assumes a straight cylinder unless radius_curvature_ratio is specified.
radius_curvature_ratio: Ratio of radius of curvature to body length (\rho_c / L). Used to compute radius_curvature if not explicitly provided. Default is NULL.
radius_cylinder_fun: Method for selecting the representative radius when the cylinder has variable radius. One of "center" (default), "mean", "median", or "max".
sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).

References

Stanton, T.K., Chu, D., Wiebe, P.H., and Clay, C.S. (1993a). Average echoes from randomly oriented random-length finite cylinders: Zooplankton models. The Journal of the Acoustical Society of America, 94: 3463-3472.

Stanton, T.K., Chu, D., Wiebe, P.H., Martin, L.V., and Eastwood, R.L. (1998). Sound scattering by several zooplankton groups. I. Experimental determination of dominant scattering mechanisms. The Journal of the Acoustical Society of America, 103: 225-235.

Stanton, T.K., Chu, D., and Wiebe, P.H. (1998). Sound scattering by several zooplankton groups. II. Scattering models. The Journal of the Acoustical Society of America, 103: 236-253.

Examples

subset(available_models(), model == "trcm")

Viscous-elastic spherical model (VESMS)

Description

Computes backscatter from a gas-filled spherical inclusion surrounded by an elastic shell and an outer viscous layer, following the wideband backscattering model used by Khodabandeloo et al. (2021). The model is parameterized on ESS objects, where the fluid slot represents the inner gas sphere and the shell slot represents the elastic shell. The external viscous layer is supplied as model-specific arguments.

Details

When radius_viscous and viscous_thickness are both omitted, the model estimates the viscous-layer radius from the neutral-buoyancy relation used by Khodabandeloo et al. (2021, Eq. 18).

Value

No value; this help topic documents the VESMS model.

Usage

This model is accessed via:

target_strength(
  ...,
  model = "VESMS",
  sound_speed_sw,
  density_sw,
  sound_speed_viscous,
  density_viscous,
  shear_viscosity_viscous,
  bulk_viscosity_viscous,
  radius_viscous,
  viscous_thickness,
  m_limit
)

Arguments

sound_speed_sw: Seawater sound speed (m~s^{-1}).
density_sw: Seawater density (kg~m^{-3}).
sound_speed_viscous: Compressional sound speed in the outer viscous layer (m~s^{-1}).
density_viscous: Density of the outer viscous layer (kg~m^{-3}).
shear_viscosity_viscous: Shear viscosity of the outer viscous layer (kg~m^{-1}~s^{-1}).
bulk_viscosity_viscous: Optional bulk viscosity of the outer viscous layer. When omitted, it defaults to the supplied shear viscosity to match the reference implementation.
radius_viscous: Optional outer radius of the viscous layer (R_2, m).
viscous_thickness: Optional thickness of the viscous layer relative to the shell outer radius. Supply either this or radius_viscous, not both.
m_limit: Optional truncation limit for the modal summation. A value of 2 retains the m = 0, 1, 2 terms. When omitted, the model uses \max(2, \mathrm{round}(k_1 R_2) + 10) at each frequency.

References

Khodabandeloo, B., Agersted, M.D., Klevjer, T., Macaulay, G.J., and Melle, W. (2021). Estimating target strength and physical characteristics of gas-bearing mesopelagic fish from wideband in situ echoes using a viscous-elastic scattering model. The Journal of the Acoustical Society of America, 149, 673-691.

Feuillade, C., and Nero, R.W. (1998). A viscous-elastic swimbladder model for describing enhanced-frequency resonance scattering from fish. The Journal of the Acoustical Society of America, 103, 3245-3255.

Anson, D.S., and Chivers, R.C. (1993). An irregular frequencies solution to acoustic scattering by elastic spheres. The Journal of the Acoustical Society of America, 93, 118-123.

Examples

subset(available_models(), model == "vesms")

Along-matrix summing function

Description

Along-matrix summing function

Usage

along_sum(rpos, iterations)

Arguments

rpos

Position vector

iterations

Number of iterations

Value

A numeric matrix containing the adjacent column sums of rpos.

Examples

positions <- matrix(1:8, nrow = 2)
along_sum(positions, ncol(positions))

Creates arbitrary body shape from user inputs

Description

Creates arbitrary body shape from user inputs

Usage

arbitrary(..., length_units = "m")

Arguments

...

Any coordinate or parameter vectors (e.g., x_body, y_body, z_body, radius_body, w_body, zU_body, zL_body, custom_*). Inputs are stored and padded to a common length; validation happens downstream in model-specific code.

length_units

Units for body length. Defaults to meters: "m"

Value

An Arbitrary shape object containing the padded position matrix and stored shape metadata.

Examples

# Symmetric arbitrary shape using x/y/z + radius
arbitrary(
  x_body = c(0, 0.01), y_body = c(0, 0), z_body = c(0, 0),
  radius_body = c(0, 0.002)
)

# Dorsal/ventral style inputs
arbitrary(
  x_body = c(0, 0.015),
  w_body = c(0.005, 0.0075),
  zU_body = c(0.001, 0.002),
  zL_body = c(-0.001, -0.002)
)

List available target-strength models

Description

List available target-strength models

Usage

available_models()

Value

A data frame describing currently available built-in and user-registered target-strength models.

Examples

head(available_models())

Generate a BBF-class object.

Description

Generate a BBF-class object.

Usage

bbf_generate(
  body_shape,
  backbone_shape,
  density_body = NULL,
  sound_speed_body = NULL,
  g_body = NULL,
  h_body = NULL,
  density_backbone,
  sound_speed_longitudinal_backbone,
  sound_speed_transversal_backbone,
  theta_body = pi/2,
  theta_backbone = pi/2,
  x_offset_backbone = 0,
  z_offset_backbone = 0,
  theta_units = "radians",
  length_units = "m",
  ID = NULL
)

Arguments

body_shape

Pre-built body shape. Must inherit from Shape.

backbone_shape

Pre-built backbone shape. Must be a cylindrical Shape.

density_body

Flesh density (ρ_body, kg m³).

sound_speed_body

Flesh sound speed (c_body, m s^-1).

g_body

Body density contrast.

h_body

Body sound speed contrast.

density_backbone

Backbone density (ρ_bb, kg m³).

sound_speed_longitudinal_backbone

Longitudinal wave speed in the backbone (m/s).

sound_speed_transversal_backbone

Transversal wave speed in the backbone (m/s).

theta_body

Body orientation relative to the incident wave (radians).

theta_backbone

Backbone orientation relative to the incident wave (radians).

x_offset_backbone

Along-body translation applied to the backbone geometry (m).

z_offset_backbone

Dorsoventral translation applied to the backbone geometry (m).

theta_units

Compatibility argument. Scatterer constructors now assume radians and ignore non-SI alternatives.

length_units

Compatibility argument. Scatterer constructors now assume meters and ignore non-SI alternatives.

ID

Optional metadata identifier.

Details

bbf_generate() is intended for swimbladder-less fish workflows where the flesh and backbone should remain explicit, separately parameterized components. The body is stored using the same segmented-body representation used by FLS, while the backbone is stored as an explicit cylindrical component carrying elastic material properties for use by cylinder-based modal models.

Value

Generates a BBF-class object.

Examples

body_shape <- arbitrary(
  x_body = c(0, 0.04, 0.08),
  zU_body = c(0.001, 0.004, 0.001),
  zL_body = c(-0.001, -0.004, -0.001)
)
backbone_shape <- cylinder(
  length_body = 0.06,
  radius_body = 0.0008,
  n_segments = 40
)
bbf_generate(
  body_shape = body_shape,
  backbone_shape = backbone_shape,
  density_body = 1070,
  sound_speed_body = 1570,
  density_backbone = 1900,
  sound_speed_longitudinal_backbone = 3500,
  sound_speed_transversal_backbone = 1700
)

Benchmark model outputs from Jech et al. (2015)

Description

A packaged list of benchmark target-strength spectra for the canonical sphere, shell-sphere, finite-cylinder, and prolate-spheroid comparison cases used throughout the package validation workflow. The stored values follow the benchmark definitions assembled by Jech et al. (2015) and distributed in the echoSMs reference resources.

Usage

data(benchmark_ts)

Format

An object of class list of length 2.

Value

A list of benchmark target-strength spectra.

Source

echoSMs benchmark resources, especially the target-definition and Jech benchmark tables archived at https://github.com/ices-tools-dev/echoSMs.

References

Jech, J.M., Horne, J.K., Chu, D., Demer, D.A., Francis, D.T.I., Gorska, N., Jones, B., Lavery, A.C., Stanton, T.K., and Reeder, D.B. (2015). Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. The Journal of the Acoustical Society of America, 138, 3742-3764. doi:10.1121/1.4937607

Jech, M., and Macaulay, G. echoSMs: Acoustic backscattering models used in aquatic ecosystem research. GitHub repository: https://github.com/ices-tools-dev/echoSMs

Examples

data("benchmark_ts", package = "acousticTS")
str(benchmark_ts, max.level = 1)

Bend a scatterer body or body component

Description

Apply a smooth curvature transformation to an existing scatterer body or to a list-like body component containing an rpos matrix. This is useful when a target should keep the same broad identity while adopting a curved centerline for model comparisons or sensitivity studies.

Usage

brake(object, radius_curvature, mode = "ratio")

Arguments

object

Dataframe or scatterer-class object

radius_curvature

Radius of curvature that can be parameterized either as a ratio relative to body length or actual measurement

mode

Either "ratio" or "measurement"

Value

A bent version of object, returned as the same broad object type with updated geometry and curvature metadata.

Examples

shape_obj <- cylinder(
  length_body = 0.05,
  radius_body = 0.003,
  n_segments = 80
)
obj <- fls_generate(
  shape = shape_obj,
  density_body = 1045,
  sound_speed_body = 1520
)

bent_obj <- brake(obj, radius_curvature = 5)
head(extract(bent_obj, c("body", "rpos", "z")))
extract(bent_obj, c("shape_parameters", "radius_curvature_ratio"))

bent_body <- brake(
  extract(obj, "body"),
  radius_curvature = 0.35,
  mode = "measurement"
)
head(bent_body$rpos["z", ])

Calculate the bulk modulus (K).

Description

Calculates the bulk modulus (K) from two of the three other elastic moduli: Young's modulus (E), shear modulus (G), or Poisson's ratio (\nu). Assumes 3D material properties.

The relationships used are:

K = \frac{E G}{3(3G - E)}

K = \frac{2G(1 + \nu)}{3(1 - 2\nu)}

K = \frac{E}{3(1 - 2\nu)}

Usage

bulk(E = NULL, G = NULL, nu = NULL)

Arguments

E

Young's modulus (Pa).

G

Shear modulus (Pa).

nu

Poisson's ratio (Dimensionless).

Value

Bulk modulus (K, Pa).

Examples

bulk(E = 3e9, G = 1.1e9)

Generate a CAL-class object.

Description

Generate a CAL-class object.

Usage

cal_generate(
  material = "WC",
  diameter = 0.0381,
  sound_speed_longitudinal = NULL,
  sound_speed_transversal = NULL,
  density_sphere = NULL,
  theta_sphere = pi,
  ID = NULL,
  diameter_units = "m",
  theta_units = "radians",
  n_segments = 100
)

Arguments

material

Material type for the solid sphere. See 'Details' for built-in material options.

diameter

Spherical diameter (m).

sound_speed_longitudinal

Longitudinal sound speed (m/s).

sound_speed_transversal

Transversal sound speed (m/s).

density_sphere

Density (kg/m^3).

theta_sphere

Backscattering direction (Default: pi radians).

ID

Optional metadata ID input.

diameter_units

Compatibility argument. cal_generate() now assumes meters and ignores non-SI alternatives.

theta_units

Compatibility argument. cal_generate() now assumes radians and ignores non-SI alternatives.

n_segments

Number of segments to discretize object shape.

Details

There are several options for the material argument:

Material	Argument	c1	c2	`\rho1`
Tungsten carbide	"WC"	6853	4171	14900
Stainless steel	"steel"	5980	3297	7970
Brass	"brass"	4372	2100	8360
Copper	"Cu"	4760	2288.5	8947
Aluminum	"Al"	6260	3080	2700

Value

Generates a CAL-class object.

Examples

cal_generate(material = "WC", diameter = 38.1e-3, n_segments = 120)

Canonicalize one shape into a canonical surrogate

Description

Build an explicit canonical surrogate shape from an existing Shape object. This is intended for workflows where a measured or segmented body should be approximated deliberately by one of the package's canonical geometries before being passed to a shape-specific model family such as SPHMS, PSMS, or FCMS.

Usage

canonicalize_shape(
  shape,
  to = c("ProlateSpheroid", "Cylinder", "Sphere", "OblateSpheroid"),
  method = c("auto", "volume", "length_volume", "profile_l2"),
  n_segments = NULL,
  diagnostics = FALSE
)

Arguments

shape

A Shape object to approximate.

to

Canonical target shape. One of "Sphere", "Cylinder", "ProlateSpheroid", or "OblateSpheroid".

method

Canonicalization rule. "auto" selects a shape-specific default: "volume" for spheres, "length_volume" for cylinders, and "profile_l2" for spheroids. "volume" preserves enclosed volume only. "length_volume" preserves body length and enclosed volume. "profile_l2" fits the target canonical profile directly to the source equivalent-radius profile by least squares.

n_segments

Optional number of segments for the returned canonical shape. Defaults to the source shape segment count.

diagnostics

Logical. If FALSE (default), return only the canonical Shape. If TRUE, return a list containing the canonical shape and fit diagnostics.

Details

canonicalize_shape() is intentionally explicit. It does not run automatically inside model calls such as target_strength(..., model = "psms"), because there is no single defensible canonicalization rule for every biological or segmented target.

When the input shape contains both an explicit width profile and upper/lower height profiles, the canonicalization step first reduces those local cross-sections to an equal-area circular radius before fitting the canonical surrogate. That keeps the reduction axisymmetric while still honoring the original local cross-sectional area more closely than a height-only radius.

The returned diagnostics report how the source and target compare in length, enclosed volume, maximum equivalent radius, and equivalent-radius profile root-mean-square error on the source x-grid. Those diagnostics are the package's recommended way to judge whether a canonical surrogate is defensible for the intended model comparison.

Value

If diagnostics = FALSE, a canonical Shape object. If diagnostics = TRUE, a list with elements:

shape: the fitted canonical Shape
diagnostics: a named list of source, target, and fit metrics

Examples

bladder_like <- arbitrary(
  x_body = c(0, 0.01, 0.02, 0.03, 0.04),
  radius_body = c(0, 0.004, 0.006, 0.004, 0)
)

psms_shape <- canonicalize_shape(
  bladder_like,
  to = "ProlateSpheroid"
)

cyl_fit <- canonicalize_shape(
  bladder_like,
  to = "Cylinder",
  diagnostics = TRUE
)
cyl_fit$diagnostics$fit$radius_nrmse

Sample cod shape with fully inflated swimbladder

Description

A pre-generated SBF scatterer containing all information required for target strength modeling. The packaged object corresponds to the historical Atlantic cod example used in the KRM literature and matches the Cod D case archived in the echoSMs KRM shape collection.

Usage

data(cod)

Format

A pre-generated SBF scatterer containing all information required for target strength modeling.

metadata

Relevant and identifying metadata (list).

model_parameters

Container for specified model parameters (list).

model

Model outputs and results (list).

body

List with:

rpos: Position matrix (x, yw, zU, zL; m).
sound_speed: Flesh sound speed (c_{body}, m/s).
density: Flesh density (\rho_{body}, kg/m^3).
theta: Orientation relative to transducer (\theta_{body}, radians).

bladder

List with:

rpos: Position matrix (x, yw, zU, zL; m).
sound_speed: Flesh sound speed (c_{bladder}, m/s).
density: Flesh density (\rho_{bladder}, kg/m^3).
theta: Orientation relative to transducer (\theta_{bladder}, radians).

shape_parameters

Named list with:

body: List with length (m), ncyl (int), theta_units (str), length_units (str).
bladder: List with length (m), ncyl (int), theta_units (str), length_units (str).

Value

A pre-generated SBF scatterer object.

Source

Historical KRM cod shape collection archived in echoSMs (https://github.com/ices-tools-dev/echoSMs) and associated with the Clay and Horne Atlantic cod example.

References

Clay, C.S., and Horne, J.K. (1994). Acoustic models of fish: The Atlantic cod (Gadus morhua). The Journal of the Acoustical Society of America, 96, 1661-1668. doi:10.1121/1.410245

Examples

data("cod", package = "acousticTS")
cod

Calculate the compressibility (`\kappa`) of a scattering boundary/interface.

Description

Calculates the compressibility contrast (\kappa) between a scattering interface and the surrounding medium. Compressibility is defined as:

K = \frac{1}{\rho c^2}

where \rho is density (kg~m^{-3}) and c is sound speed (m~s^{-1}).

The compressibility contrast is then:

\kappa = \frac{K_2 - K_1}{K_1}

where K_1 is the compressibility of the medium and K_2 is that of the target interface.

Usage

compressibility(medium, target)

Arguments

medium

Dataframe object containing density (kgm^{-3}) and sound speed (ms^{-1}) values for a fluid medium external to a scattering interface (e.g., seawater).

target

Dataframe object containing density (kgm^{-3}) and sound speed (ms^{-1}) values for a target boundary.

Value

Compressibility contrast (\kappa), dimensionless.

Examples

seawater <- data.frame(density = 1026, sound_speed = 1480)
animal <- data.frame(density = 1050, sound_speed = 1530)
compressibility(seawater, animal)

A wrapper function that automatically creates generalized and/or canonical shapes for TS modeling.

Description

A wrapper function that automatically creates generalized and/or canonical shapes for TS modeling.

Usage

create_shape(shape, ...)

Arguments

shape

Shape. Details for shape specification are provided under 'Details', including mandatory arguments.

...

Additional input arguments for subsequent shape generation functions.

Details

The shape argument specifies what shape for the function to generate the desired shape for TS modeling. Options currently include:

Object shape	shape = ...	Parameters	Root function
Discrete/tapered cylinder	"cylinder"	length, radius	`cylinder(...)`
Polynomial cylinder	"polynomial_cylinder"	length, radius, polynomial	`polynomial_cylinder(...)`
Oblate spheroid	"oblate_spheroid"	length, radius	`oblate_spheroid(...)`
Prolate spheroid	"prolate_spheroid"	length, radius	`prolate_spheroid(...)`
Sphere	"sphere"	radius	`sphere(...)`

Model Parameter Definitions

length: the x-axis length of the shape.
radius: the radius of the shape when applicable.
length_radius_ratio: the length-to-radius ratio (L/A), which specifically refers to the radius at the mid-point of the cylinder and should be the maximum value. A typical L/A ratio in the literature is 16 for krill.
taper: the taper order (n), which parameterizes the tapering function reported by Chu et al. (1993) to create a tapered cylinder. The tapering order will converge on a prolate and oblate spheroid when L > 2a and L < 2a, respectively, and n = 2. A typical taper order in the literature is 10.
polynomial: the vector of arbitrary polynomial coefficients to generate a deformed cylinder as reported by Smith et al. (2013). Although listed as a mandatory argument for the polynomial cylinder function, it has a default setting that uses the sixth-degree polynomial coefficients reported by Smith et al. (2013).

Value

A Shape object.

Examples

create_shape("sphere", radius_body = 0.01)
create_shape(
  "prolate_spheroid",
  length_body = 0.04, radius_body = 0.004
)
create_shape(
  "oblate_spheroid",
  length_body = 0.012, radius_body = 0.01
)
create_shape(
  "cylinder",
  length_body = 0.05, radius_body = 0.003
)

Creates a cylinder.

Description

Creates a cylinder.

Usage

cylinder(length_body, radius_body = NULL, length_radius_ratio = NULL,
  taper = NULL, radius_curvature_ratio = NULL, n_segments = 100,
  length_units = "m")

Arguments

length_body

Length (m).

radius_body

Maximum/uniform radius (m).

length_radius_ratio

Optional ratio input when radius is not explicitly known.

taper

Optional input that is the degree of taper to round ends of the cylinder.

radius_curvature_ratio

Optional curvature ratio metadata for rounded cylinder-end workflows.

n_segments

Number of segments to discretize object shape. Defaults to 1e2 segments.

length_units

Units (default is meters, "m").

Value

Creates the position vector for a tapered or untapered cylinder.

Examples

cylinder(length_body = 0.05, radius_body = 0.003, n_segments = 80)

Convert angular measurements from radians to degrees

Description

Convert angular measurements from radians to degrees

Usage

degrees(x)

Arguments

x

A real value in radians

Value

Angle in degrees

Examples

orientation <- pi / 2 # radians
degrees(orientation) # this should return a value equal to 90 degrees

Generate a ELA-class object.

Description

Generate a ELA-class object.

Usage

ela_generate(
  shape,
  density_body = NULL,
  sound_speed_longitudinal_body = NULL,
  sound_speed_transversal_body = NULL,
  theta_body = pi/2,
  ID = NULL,
  length_units = "m",
  theta_units = "radians"
)

Arguments

shape

Pre-built Shape object describing the elastic target geometry.

density_body

Optional body density (kg/m^3).

sound_speed_longitudinal_body

Optional longitudinal wave speed (m/s).

sound_speed_transversal_body

Optional transversal wave speed (m/s).

theta_body

Body orientation relative to the incident wave (radians).

ID

Optional metadata identifier.

length_units

Compatibility argument. Scatterer constructors now assume meters and ignore non-SI alternatives.

theta_units

Compatibility argument. Scatterer constructors now assume radians and ignore non-SI alternatives.

Details

ela_generate() builds a generic solid-elastic scatterer under the shared ELA class. Unlike CAL, it is not restricted to spheres, so it can carry prolate, oblate, cylindrical, or arbitrary elastic shapes together with the body density and longitudinal/transversal wave speeds used by solid-elastic models such as TMM.

Value

ELA-class object.

Examples

elastic_sphere <- sphere(radius_body = 0.01, n_segments = 40)
ela_generate(
  shape = elastic_sphere,
  density_body = 7800,
  sound_speed_longitudinal_body = 5900,
  sound_speed_transversal_body = 3200
)

Generate an ESS-class object

Description

Generate an ESS-class object

Usage

ess_generate(
  shape = NULL,
  x_body = NULL,
  y_body = NULL,
  z_body = NULL,
  radius_shell = NULL,
  shell_thickness = NULL,
  g_fluid = NULL,
  density_fluid = NULL,
  h_fluid = NULL,
  sound_speed_fluid = NULL,
  g_shell = NULL,
  density_shell = NULL,
  h_shell = NULL,
  sound_speed_shell = NULL,
  E = NULL,
  G = NULL,
  K = NULL,
  nu = NULL,
  theta_shell = pi/2,
  ID = NULL,
  theta_units = "radians",
  length_units = "m"
)

Arguments

shape

Pre-built Shape object describing the outer shell geometry. If omitted, explicit shell profile coordinates such as x_body, y_body, and z_body are treated as the manual geometry pathway. Legacy character dispatch such as "sphere" is retained only for backward compatibility and is now deprecated.

x_body

Vector containing x-axis body (m) shape data.

y_body

Vector containing y-axis body (m) shape data.

z_body

Vector containing z-axis body (m) shape data.

radius_shell

Radius of shell (m).

shell_thickness

Optional shell thickness (m).

g_fluid

Optional density contrast for fluid-like body.

density_fluid

Optional density for fluid-like body (kg/m³).

h_fluid

Optional sound speed contrast for fluid-like body.

sound_speed_fluid

Optional sound speed for fluid-like body (m/s).

g_shell

Density contrast for the shell.

density_shell

Optional density for the shell (kg/m³).

h_shell

Sound speed contrast for the shell.

sound_speed_shell

Optional sound speed for the shell (m/s).

E

Young's modulus (Pa) of the shell material.

G

Shear modulus (Pa) of the shell material.

K

Bulk modulus (Pa) of the shell material.

nu

Poisson's ratio (Dimensionless) of the shell material.

theta_shell

Object orientation relative to incident sound wave.

ID

Optional metadata entry.

theta_units

Compatibility argument. Scatterer constructors now assume radians and ignore non-SI alternatives.

length_units

Compatibility argument. Scatterer constructors now assume meters and ignore non-SI alternatives.

Details

The preferred workflow is to build the shell geometry first as a Shape object and pass it through shape, or to supply explicit shell profile coordinates directly. Character-based shape dispatch remains available only as a compatibility pathway and is now deprecated. Material properties for both the shell and the inner fluid may be supplied either as contrasts or as absolute values, but each property pair must use only one representation.

Scatterer constructors store geometry in meters and orientations in radians. length_units and theta_units are retained as compatibility arguments, but non-SI values are normalized to the package-standard representation.

Value

ESS-class object

Examples

shell <- sphere(radius_body = 0.03, n_segments = 80)
ess_generate(
  shape = shell,
  shell_thickness = 0.001,
  density_shell = 1050,
  sound_speed_shell = 2350,
  density_fluid = 1030,
  sound_speed_fluid = 1500,
  E = 3.5e9,
  nu = 0.34
)

Extract nested components, slots, or matrix/vector fields from objects

Description

Convenience accessor for reaching into Scatterer and Shape objects without spelling out direct slot access repeatedly. extract() can also walk through nested lists, matrices, and named vectors, which makes it useful for pulling model outputs, component properties, or position-matrix fields from a common interface. This is especially helpful after geometry manipulations such as brake() and reforge(), where inspecting the stored body profile is often the fastest way to confirm what changed.

Usage

extract(object, feature)

Arguments

object

Scatterer-class object.

feature

Feature(s) of interest (e.g. body). This can either be a scalar string, or a vector of names. When a vector is supplied, the function recursively accesses the Scatterer object using the 'feature' vector as a directory. For example, feature = c("body", "rpos", "x") would extract the 'x' coordinate of the position matrix ('rpos') from the 'body' scattering parameters.

Value

The extracted object, slot, list element, matrix row/column, or vector element identified by feature.

Examples

obj <- fls_generate(
  shape = sphere(radius_body = 0.01, n_segments = 40),
  density_body = 1045,
  sound_speed_body = 1520
)

extract(obj, "body")
extract(obj, c("body", "density"))
extract(obj, c("shape_parameters", "shape"))

bent_obj <- brake(obj, radius_curvature = 5)
head(extract(bent_obj, c("body", "rpos", "z")))
extract(bent_obj, c("shape_parameters", "radius_curvature_ratio"))

Flip a stored shape or scatterer profile across the x or z axis

Description

Reverse axial orientation (axis = "x") or mirror the geometry dorsoventrally (axis = "z") without manually editing the position matrix.

Usage

flip_shape(
  object,
  axis = c("x", "z"),
  component = NULL,
  containment = c("warn", "error", "ignore")
)

Arguments

object

Shape or Scatterer object.

axis

Flip axis. Use "x" to reverse nose/tail orientation while keeping the existing x grid, or "z" to mirror the profile vertically.

component

Optional component name for scatterers. Defaults to the primary geometry ("body" for most scatterers and "shell" for ESS).

containment

Containment policy used when a moved swimbladder or backbone is checked against its body: "warn", "error", or "ignore".

Value

The modified object, returned as the same broad object type.

Examples

shape_obj <- arbitrary(
  x_body = c(0, 0.01, 0.02, 0.03),
  radius_body = c(0, 0.004, 0.002, 0)
)
flipped_shape <- flip_shape(shape_obj, axis = "x")
head(extract(flipped_shape, c("position_matrix", "zU")))

Generate a FLS-class object.

Description

Generate a FLS-class object.

Usage

fls_generate(
  shape = NULL,
  x_body = NULL,
  y_body = NULL,
  z_body = NULL,
  length_body = NULL,
  radius_body = NULL,
  radius_curvature_ratio = NULL,
  n_segments = 18,
  g_body = NULL,
  h_body = NULL,
  density_body = NULL,
  sound_speed_body = NULL,
  theta_body = pi/2,
  ID = NULL,
  length_units = "m",
  theta_units = "radians",
  ...
)

Arguments

shape

Pre-built Shape object describing the target geometry. If omitted, explicit profile coordinates such as x_body, y_body, and z_body are treated as the manual geometry pathway. Legacy character dispatch such as "sphere" or "arbitrary" is retained only for backward compatibility and is now deprecated.

x_body

Vector containing x-axis body (m) shape data.

y_body

Vector containing y-axis body (m) shape data.

z_body

Vector containing z-axis body (m) shape data.

length_body

Optional input for a generic length value input.

radius_body

Vector containing radii (m).

radius_curvature_ratio

Length-to-curvature ratio (pc/L).

n_segments

Number of body segments.

g_body

Density contrast. This can either be a single value (i.e. homogenous) or a vector of values (i.e. inhomogenous).

h_body

Sound-speed contrast. This can either be a single value (i.e. homogenous) or a vector of values (i.e. inhomogenous).

density_body

Absolute density (kg/m^3) if contrasts are not supplied.

sound_speed_body

Absolute sound speed (m/s) if contrasts are not supplied.

theta_body

Orientation of the target relative to the transmit source (\theta). Broadside incidence is considered 90 degrees, or pi/2. Default value is pi/2; input should be in radians.

ID

Optional metadata entry.

length_units

Compatibility argument. Scatterer constructors now assume meters and ignore non-SI alternatives.

theta_units

Compatibility argument. Scatterer constructors now assume radians and ignore non-SI alternatives.

...

Additional parameters.

Details

The preferred workflow is to build a geometry first with sphere(), cylinder(), prolate_spheroid(), or arbitrary(), then pass that Shape object to fls_generate(). Material properties can be supplied either as contrasts (g_body/h_body) or as absolute density/sound-speed values (density_body/sound_speed_body), but not both for the same property pair. Downstream models derive contrasts automatically when only absolute values are supplied.

The only supported public geometry paths are now:

supply a pre-built Shape object, or
supply explicit profile coordinates directly to the constructor.

Character-based shape dispatch is retained only as a compatibility pathway and is now deprecated. Internally, every pathway is resolved to the same Shape-first geometry contract before the FLS object is built.

Value

FLS-class object

Examples

shape <- prolate_spheroid(
  length_body = 0.04, radius_body = 0.004, n_segments = 50
)
fls_generate(
  shape = shape, density_body = 1045, sound_speed_body = 1520
)

Generate a GAS-class object

Description

Generate a GAS-class object

Usage

gas_generate(shape = NULL, radius_body = NULL, h_fluid = 0.22,
  g_fluid = 0.0012, sound_speed_fluid = NULL, density_fluid = NULL,
  theta_body = pi/2, ID = NULL, radius_units = "m",
  theta_units = "radians", n_segments = 100, ...)

Arguments

shape

Pre-built Shape object describing the gas-filled geometry. If omitted, explicit profile coordinates such as x_body, y_body, and z_body are treated as the manual geometry pathway. Legacy character dispatch such as "sphere" is retained only for backward compatibility and is now deprecated.

radius_body

Radius (m). For non-canonical shapes, this would be the maximum or mean radius at the scatterer midsection.

h_fluid

Sound speed contrast of fluid relative to surrounding medium (h).

g_fluid

Density contrast of fluid relative to surrounding density (g).

sound_speed_fluid

Optional fluid sound speed (m/s).

density_fluid

Optional fluid density (m/s).

theta_body

Orientation of the target relative to the incident wave (radians).

ID

Optional metadata identifier.

radius_units

Compatibility argument. gas_generate() now assumes meters and ignores non-SI alternatives.

theta_units

Compatibility argument. Scatterer constructors now assume radians and ignore non-SI alternatives.

n_segments

Number of body segments.

...

Additional manual profile arguments or legacy canonical shape arguments used by the compatibility geometry pathway, such as x_body, y_body, z_body, radius_body, length_body, or taper.

Details

The preferred workflow is to supply a pre-built Shape object or explicit profile coordinates and then describe the internal gas by either contrasts (g_fluid, h_fluid) or absolute density/sound-speed values (density_fluid, sound_speed_fluid). Character-based shape dispatch remains available only as a compatibility pathway and is now deprecated.

Scatterer constructors store geometry in meters and orientations in radians. radius_units and theta_units are retained as compatibility arguments, but non-SI values are normalized to the package-standard representation.

Value

GAS-class object

Examples

shape_gas <- sphere(radius_body = 0.01, n_segments = 60)
gas_generate(shape = shape_gas, g_fluid = 0.0012, h_fluid = 0.22)

Gauss-Legendre nodes and weights

Description

Compute Gauss-Legendre quadrature nodes and weights on an interval [a,~b].

Usage

gauss_legendre(n, a = -1, b = 1)

Arguments

n

Number of quadrature nodes (n >= 1).

a

Left endpoint of the integration interval.

b

Right endpoint of the integration interval (b > a).

Details

Gauss-Legendre quadrature provides exact integration for polynomials of degree up to 2n-1 using n nodes and weights chosen as the roots of the Legendre polynomial P_n(x) on the canonical interval [-1,1]. For a general interval [a,b] the canonical nodes are shifted and rescaled onto [a,b], and the weights are scaled by (b-a)/2.

This wrapper performs basic argument validation and calls the C++ routine to obtain nodes and weights with high accuracy for moderate n.

Value

A list with components:

nodes: Quadrature abscissae x_i in [a,~b].
weights: Quadrature weights w_i such that \int_a^b f(x)\,dx \approx \sum_{i=1}^n w_i\,f(x_i).

References

Davis, P. J., & Rabinowitz, P. (2007). Methods of Numerical Integration (2nd ed.).

Examples

rule <- gauss_legendre(n = 4, a = 0, b = 1)
sum(rule$weights * rule$nodes^2)

Cylindrical Bessel function of the third kind (Hankel), `H_\nu(x)`, and its respective derivatives

Description

Computes the cylindrical Hankel function of the first kind (H^{(1)}_\nu(z)) and its derivatives through hcdk().

Usage

hc(l, n)

hcdk(l, n, k)

Arguments

l

Numeric. The order (\nu) of the Hankel function. Must be purely real; complex orders are not supported.

n

Numeric or complex. The argument (z) at which to evaluate the function. Supports purely real or purely imaginary values. General complex arguments are not supported.

k

Non-negative integer. The order of the derivative for hcdk.

Details

The Hankel function of the first kind is defined as:

H^{(1)}_\nu(z) = J_\nu(z) + i Y_\nu(z)

where J_\nu(z) is the Bessel function of the first kind and Y_\nu(z) is the Bessel function of the second kind.

Supported argument types: Since H^{(1)}_\nu(z) is computed from J_\nu(z) and Y_\nu(z), the same restrictions apply:

Purely real arguments (z = x): Fully supported.
Purely imaginary arguments (z = iy): Supported.
General complex arguments (z = x + iy): Not supported.

Derivatives:

First derivative: \frac{d}{dz}H^{(1)}_\nu(z) = \frac{\nu}{z} H^{(1)}_\nu(z) - H^{(1)}_{\nu+1}(z)
Second derivative: \frac{d^2}{dz^2}H^{(1)}_\nu(z) = H^{(1)}_{\nu-2}(z) - \frac{2\nu-1}{z} H^{(1)}_{\nu-1}(z) + \frac{\nu^2+\nu}{z^2} H^{(1)}_\nu(z)
k-th derivative (DLMF 10.6.1): \frac{d^k}{dz^k}H^{(1)}_\nu(z) = \frac{1}{2^k} \sum_{j=0}^{k} (-1)^j \binom{k}{j} H^{(1)}_{\nu-k+2j}(z)

Value

A complex vector containing:

hc: H^{(1)}_\nu(z)
hcdk(..., k = 1): \frac{d}{dz}H^{(1)}_\nu(z) (first derivative)
hcdk(..., k = 2): \frac{d^2}{dz^2}H^{(1)}_\nu(z) (second derivative)
hcdk: \frac{d^k}{dz^k}H^{(1)}_\nu(z) (k-th derivative)

References

Abramowitz, M. and Stegun, I.A. (Eds.). (1964). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables. National Bureau of Standards, Applied Mathematics Series 55. Chapter 9.

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

Hankel function definition: https://dlmf.nist.gov/10.2
k-th derivative formula: Eq. 10.6.1 at https://dlmf.nist.gov/10.6

Examples

# Hankel function
hc(0, 1)
hc(1, 2.5)

# Fractional order
hc(0.5, 3)

# Purely imaginary argument
hc(1, 1i)

# First derivative
hcdk(1, 2, 1)

# Second derivative
hcdk(1, 2, 2)

# k-th derivative
hcdk(1, 2, 3) # Third derivative

Spherical Bessel function of the third kind (Hankel), `h_\nu(x)`, and its respective derivatives

Description

Computes the spherical Hankel function of the first kind (h^{(1)}_\nu(z)) and its first-th derivative.

Usage

hs(l, n)

hsdk(l, n, k)

Arguments

l

Numeric. The order of the spherical Hankel function. Can be integer or fractional.

n

Numeric. The argument (z) at which to evaluate the function.

k

Non-negative integer. The order of the derivative for hsdk.

Details

The spherical Hankel function of the first kind is defined as:

h^{(1)}_\nu(z) = j_\nu(z) + i y_\nu(z)

where j_\nu(z) is the spherical Bessel function of the first kind and y_\nu(z) is the spherical Bessel function of the second kind.

It is related to the cylindrical Hankel function by:

h^{(1)}_\nu(z) = \sqrt{\frac{\pi}{2z}} H^{(1)}_{\nu+1/2}(z)

The spherical Hankel functions are used extensively in scattering theory to represent outgoing spherical waves.

Derivative:

\frac{d}{dz}h^{(1)}_\nu(z) = \frac{\nu}{z} h^{(1)}_\nu(z) - h^{(1)}_{\nu+1}(z)

Value

A complex vector containing:

hs: h^{(1)}_\nu(z)
hsdK: \frac{d}{dz^k}h^{(1)}_l(z) (k-th derivative)

References

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

Spherical Bessel functions: https://dlmf.nist.gov/10.47
Relation to cylindrical Hankel functions: Eq. 10.47.5 at https://dlmf.nist.gov/10.47

Examples

# Spherical Hankel function
hs(0, 1)
hs(1, 2.5)

# Fractional order
hs(0.5, 3)

# Vector input
hs(0, c(1, 2, 3))

# First derivative
hsdk(1, 2, 1)

Locally widen, pinch, or taper a stored shape profile

Description

Apply a localized scaling window to a stored profile. Values of scale > 1 inflate the selected region, while scale < 1 pinch or taper it. For canonical Shape objects, the result is returned as an Arbitrary shape because the edited profile is no longer guaranteed to preserve the canonical class geometry.

Usage

inflate_shape(
  object,
  x_range = NULL,
  scale = 1,
  component = NULL,
  axis = c("radius", "width", "height"),
  profile = c("cosine", "linear", "box"),
  containment = c("warn", "error", "ignore")
)

Arguments

object

Shape or Scatterer object.

x_range

Optional axial interval over which the local manipulation is applied.

scale

Positive local scale factor.

component

Optional component name for scatterers. Defaults to the primary geometry ("body" for most scatterers and "shell" for ESS).

axis

Which profile dimension to scale.

profile

Local window profile. "cosine" gives a smooth bump centered inside x_range, "linear" gives a triangular bump, and "box" applies a uniform factor inside the interval.

containment

Containment policy used when a moved swimbladder or backbone is checked against its body: "warn", "error", or "ignore".

Value

The modified object. Shape inputs that are locally reshaped are returned as Arbitrary shapes.

Examples

shape_obj <- cylinder(
  length_body = 0.05, radius_body = 0.003,
  n_segments = 80
)
pinched_shape <- inflate_shape(
  shape_obj,
  x_range = c(0.015, 0.035),
  scale = 0.7
)
max(extract(pinched_shape, c("shape_parameters", "max_radius")))

Cylindrical Bessel function of the first kind, `J_\nu(z)`, and its respective derivatives

Description

Computes the cylindrical Bessel function of the first kind (J_\nu(z)) and its k-th derivatives.

Usage

jc(l, n)

jcdk(l, n, k)

Arguments

l

Numeric. The order (\nu) of the Bessel function. Must be purely real; complex orders are not supported.

n

Numeric or complex. The argument (z) at which to evaluate the function. Supports purely real or purely imaginary values. General complex arguments (x + iy with x \neq 0 and y \neq 0) are not supported.

k

Non-negative integer. The order of the derivative for jcdk.

Details

The cylindrical Bessel function of the first kind satisfies Bessel's differential equation:

z^2 \frac{d^2 J_\nu}{dz^2} + z \frac{dJ_\nu}{dz} + (z^2 - \nu^2) J _\nu = 0

Supported argument types:

Purely real arguments (z = x, where x \in \mathbb{R}): Fully supported for both positive and negative values.
Purely imaginary arguments (z = iy, where y \in \mathbb{R}): Computed using the identity J_\nu(iy) = e^{i\pi\nu/2} I_\nu(y) where I_\nu is the modified Bessel function of the first kind.
General complex arguments (z = x + iy, where x \neq 0 and y \neq 0): Not supported.

Special cases:

J_\nu(0) = 1 if \nu = 0, otherwise J_\nu(0) = 0.
For negative real arguments with integer order n: J_n(-x) = (-1)^n J_n(x).
For negative real arguments with non-integer order \nu: J_\nu(-x) = e^{i\pi\nu} J_\nu(x) (complex result).

Derivatives:

First derivative: J'_\nu(z) = J_{\nu-1}(z) - \frac{\nu}{z} J_\nu(z)
Second derivative: J''_\nu(z) = \frac{1}{4}\left[J_{\nu-2}(z) - 2J_\nu(z) + J_{\nu+2}(z)\right]
k-th derivative (DLMF 10.6.1):

\frac{d^k}{dz^k} J_\nu(z) = \frac{1}{2^k} \sum_{j=0}^{k} (-1)^j \binom{k}{j} J_{\nu - k + 2j}(z)

Value

A complex vector containing:

jc: J_\nu(z)
jcdk(..., k = 1): J'_\nu(z) (first derivative)
jcdk(..., k = 2): J''_\nu(z) (second derivative)
jcdk: J_\nu^{(k)}(z) (k-th derivative)

References

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

Bessel's equation: https://dlmf.nist.gov/10.2
Negative argument identity (J_\nu(-z)): Eq. 10.4.1 at https://dlmf.nist.gov/10.4
Imaginary argument identity (J_\nu(iz)): Eq. 10.27.6 at https://dlmf.nist.gov/10.27

Examples

# Real argument, integer order
jc(0, 1)
jc(1, 2.5)

# Real argument, fractional order
jc(0.5, 3)

# Negative real argument (integer order gives real result)
jc(2, -1.5)

# Negative real argument (fractional order gives complex result)
jc(0.5, -2)

# Purely imaginary argument
jc(1, 1i)
jc(2, 3i)

# First derivative
jcdk(1, 2, 1)

# Second derivative
jcdk(1, 2, 2)

Spherical Bessel function of the first kind, `j_\nu(z)`, and its respective derivatives

Description

Computes the spherical Bessel function of the first kind (j_\nu(z)) and its k-th derivative.

Usage

js(l, n)

jsdk(l, n, k)

Arguments

l

Numeric. The order of the spherical Bessel function. Can be integer or fractional.

n

Numeric or matrix. The argument (z) at which to evaluate the function. If a matrix is provided, the function is applied column-wise.

k

Non-negative integer. The order of the derivative for jsdk.

Details

The spherical Bessel function of the first kind is related to the cylindrical Bessel function by:

j_\nu(z) = \sqrt{\frac{\pi}{2z}} J_{\nu+1/2}(z)

where J_\nu(z) is the cylindrical Bessel function of the first kind.

The spherical Bessel functions satisfy the differential equation:

z^2 \frac{d^2 j_\nu}{dz^2} + 2z \frac{dj_\nu}{dz} + [z^2 - l(l+1)] j_\nu = 0

Special cases:

j_\nu(0) = 0 for all \nu.
j_0(z) = \frac{\sin(z)}{z}
j_1(z) = \frac{\sin(z)}{z^2} - \frac{\cos(z)}{z}

Derivatives:

First derivative: j'_\nu(z) = j_{\nu-1}(z) - \frac{\nu+1}{z} j_\nu(z)
Second derivative: j''_\nu(z) = \frac{(\nu+1)(\nu+2) - z^2}{z^2} j_\nu(z) - \frac{2}{z} j_{\nu-1}(z)

Value

A numeric vector or matrix (matching the input structure) containing:

js: j_\nu(z)
jsdk: j^{(k)'}_l(z) (k-th derivative)

References

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

Spherical Bessel functions: https://dlmf.nist.gov/10.47
Relation to cylindrical Bessel functions: Eq. 10.47.3 at https://dlmf.nist.gov/10.47

Examples

# Spherical Bessel function
js(0, 1)
js(1, 2.5)

# Fractional order
js(0.5, 3)

# Vector input
js(0, c(1, 2, 3))

# Matrix input (applied column-wise)
js(1, matrix(1:6, nrow = 2))

# First derivative
jsdk(1, 2, 1)

# Second derivative
jsdk(1, 2, 2)

Sample krill (Euphausia superba) shape taken from McGehee et al. (1998)

Description

A dataset containing a sample krill (Euphausia superba) body shape proposed by McGehee et al. (1998).

Usage

data(krill)

Format

A pre-generated FLS scatterer containing all information required for target strength modeling.

metadata

Relevant and identifying metadata (list).

model_parameters

Container for specified model parameters (list).

model

Model outputs and results (list).

body

A list with elements:

rpos: Position matrix (x, y, z; m).
radius: Radius of each discrete cylinder (m).
g: Body density contrast relative to medium.
h: Sound speed contrast relative to medium.
theta: Orientation angle (\theta_{body}, radians).

shape_parameters

A list with:

length: Body length (m).
ncyl: Number of cylinders.
theta_units: Unit of orientation.
length_units: Unit of length.

Value

A pre-generated FLS scatterer object.

Examples

data("krill", package = "acousticTS")
krill

Calculate Lamé's first parameter (`\lambda`)

Description

Calculates Lamé's first parameter (\lambda) from two of the four other elastic moduli: bulk modulus (K), Young's modulus (E), shear modulus (G), or Poisson's ratio (\nu). Assumes 3D material properties.

The relationships used are:

\lambda = K - \frac{2G}{3}

\lambda = \frac{E\nu}{(1 + \nu)(1 - 2\nu)}

\lambda = \frac{2G\nu}{1 - 2\nu}

\lambda = \frac{3K\nu}{1 + \nu}

\lambda = \frac{3K(3K - E)}{9K - E}

\lambda = \frac{G(E - 2G)}{3G - E}

Usage

lame(K = NULL, E = NULL, G = NULL, nu = NULL)

Arguments

K

Bulk modulus (Pa).

E

Young's modulus (Pa).

G

Shear modulus (Pa).

nu

Poisson's ratio (Dimensionless).

Value

Lamé's first parameter (\lambda, Pa).

Examples

lame(K = 2.5e9, G = 1.1e9)

Convert between logarithmic (dB) and linear domains for backscatter values.

Description

The linear function converts a value from the logarithmic (dB) domain to the linear domain, while the db function converts a value from the linear domain to the logarithmic (dB) domain. These are commonly used for target strength (TS) and backscattering coefficient (\sigma_{bs}) conversions.

The conversions are defined as:

\text{linear}(x) = c^{x / c}

\text{db}(x) = c \log_c(x)

where c is the coefficient (default 10).

Usage

linear(value, coefficient = 10)

db(value, coefficient = 10)

Arguments

value

Numeric value to convert. For linear, this is a logarithmic value (e.g., dB TS); for db, this is a linear value (e.g., \sigma_{bs}).

coefficient

Optional. Numeric coefficient (base) for the logarithm. Default is 10.

Value

For linear, returns the value converted to the linear domain. For db, returns the value converted to the logarithmic (dB) domain.

Examples

sigma_bs <- linear(-40)
db(sigma_bs)

Compute the Neumann factor `\nu_{n}`

Description

The Neumann factor, denoted \nu_{n}, is a simple multiplicative constant commonly used in spherical or spheroidal function theory. It accounts for the symmetry of cosine terms or the duplication of even-order contributions in integrals.

Usage

neumann(x)

Arguments

x

An integer iterator.

Details

Formally, the Neumann factor is defined as:

\eta_n = \begin{cases} 1, & n = 0, \\ 2, & n > 0. \end{cases}

This factor frequently appears in the normalization of spherical Bessel functions, Legendre expansions, and spheroidal wave functions. It is not related to the "von Neumann ordinals" used in set theory.

Value

A numeric vector of the same length as x, containing values of \eta_x, each equal to 1 or 2.

Examples

neumann(0) # should return 1
neumann(1) # should return 2
neumann(2) # should return 2

# Vectorized use:
neumann(0:4)

Creates an oblate spheroid.

Description

Creates an oblate spheroid.

Usage

oblate_spheroid(
  length_body = NULL,
  radius_body = NULL,
  length_radius_ratio = NULL,
  semimajor_length = NULL,
  semiminor_length = NULL,
  n_segments = 100,
  length_units = "m"
)

Arguments

length_body

Body-axis length (m).

radius_body

Maximum equatorial radius (m).

length_radius_ratio

Optional ratio input when radius is not explicitly known.

semimajor_length

Optional alias for maximum equatorial radius (m).

semiminor_length

Optional alias for body-axis semi-length (m).

n_segments

Number of segments to discretize object shape. Defaults to 100 segments.

length_units

Units for body matrix (defaults to m).

Value

Creates the position vector for an oblate spheroid object of defined body-axis length and maximum equatorial radius.

Examples

oblate_spheroid(
  length_body = 0.012, radius_body = 0.01, n_segments = 60
)
oblate_spheroid(
  semiminor_length = 0.006, semimajor_length = 0.01
)

Offset an internal scatterer component without rebuilding the object

Description

Translate an internal geometry-bearing component such as a swimbladder or backbone while leaving the outer body unchanged.

Usage

offset_component(
  object,
  component = c("bladder", "backbone"),
  x_offset = 0,
  z_offset = 0,
  containment = c("warn", "error", "ignore")
)

Arguments

object

Scatterer object containing an internal component.

component

Internal component name. Currently most useful for "bladder" and "backbone".

x_offset

Along-axis translation (m).

z_offset

Vertical translation (m).

containment

Containment policy used when the shifted component is checked against the body: "warn", "error", or "ignore".

Value

The modified scatterer object.

Examples

fish <- sbf_generate(
  x_body = c(0, 0.1),
  w_body = c(0.006, 0.008),
  zU_body = c(0.001, 0.002),
  zL_body = c(-0.001, -0.002),
  x_bladder = c(0.02, 0.08),
  w_bladder = c(0, 0),
  zU_bladder = c(0.0012, 0.0012),
  zL_bladder = c(-0.0012, -0.0012),
  density_body = 1040,
  density_bladder = 1.2,
  sound_speed_body = 1500,
  sound_speed_bladder = 340
)
shifted_fish <- offset_component(
  fish,
  component = "bladder",
  x_offset = 0.003
)
min(extract(shifted_fish, c("bladder", "rpos", "x_bladder")))

Plot scatterer geometry, stored model results, or stored TMM scattering views

Description

S3 plotting method for Scatterer objects. Depending on type, the method draws the target geometry, one or more stored model curves, or a stored single-target TMM scattering slice / map when the object was computed with retained T-matrix state.

Usage

## S3 method for class 'Scatterer'
plot(
  x,
  y = NULL,
  type = "shape",
  nudge_y = 1.1,
  nudge_x = 1.05,
  aspect_ratio = "manual",
  x_units = "frequency",
  y_units = "TS",
  ...
)

Arguments

x

Scatterer-class object.

y

Ignored (required for the base plot() method signature).

type

Plot mode. Use "shape" for the stored geometry, "model" for the currently stored model output, or "scattering" for stored TMM angular products.

nudge_y

Multiplicative vertical padding applied to automatically derived y-axis limits.

nudge_x

Multiplicative horizontal padding applied to automatically derived x-axis limits.

aspect_ratio

Aspect-ratio control for supported shape plots. Use "manual" to honor nudge_x / nudge_y, or "auto" to let the plotting helper derive the aspect ratio directly.

x_units

Horizontal-axis convention for type = "model". Supported values depend on the stored model family and typically include "frequency" and geometry-scaled wavenumber variants such as "ka".

y_units

Stored response quantity for type = "model" or type = "scattering". Typical values include "TS" and "sigma_bs".

...

Additional arguments passed through to the class-specific plotting helpers. For stored TMM scattering plots, this includes controls such as frequency, vary, polar, and heatmap.

Details

Plotting behavior is selected from the object's class. The supported type values therefore depend on what has been stored on the object. For example, type = "model" requires the object to already contain model output, and type = "scattering" currently applies only to stored TMM results.

Value

Called for its side effect of drawing a plot; returns the input invisibly.

Examples

data("krill", package = "acousticTS")
plot(krill)

Calculate the Poisson's ratio (`\nu`)

Description

Calculates Poisson's ratio (\nu) from two of the three other elastic moduli: bulk modulus (K), Young's modulus (E), or shear modulus (G). Assumes 3D material properties.

The relationships used are:

\nu = \frac{E}{2G} - 1

\nu = \frac{3K - 2G}{2(3K + G)}

\nu = \frac{3K - E}{6K}

Usage

pois(K = NULL, E = NULL, G = NULL)

Arguments

K

Bulk modulus (K, Pa).

E

Young's modulus (E, Pa).

G

Shear modulus (Pa).

Value

Poisson's ratio (\nu), dimensionless.

Examples

pois(E = 3e9, G = 1.1e9)

Creates a polynomial deformed cylinder

Description

Creates a polynomial deformed cylinder

Usage

polynomial_cylinder(
  length_body,
  radius_body,
  n_segments = 100,
  polynomial,
  length_units = "m"
)

Arguments

length_body

Length (m).

radius_body

Maximum/uniform radius (m).

n_segments

Number of segments to discretize object shape. Defaults to 1e2 segments.

polynomial

Polynomial coefficient vector.

length_units

Units (default is meters, "m").

Value

Creates the position vector for a polynomial deformed cylinder.

References

Smith, J.N., Ressler, P.H., and Warren, J.D. 2013. A distorted wave Born approximation target strength model for Bering Sea euphausiids. ICES Journal of Marine Science, 70(1): 204-214. https://doi.org/10.1093/icesjms/fss140

Examples

# We can use the polynomial coefficients defined in Smith et al. (2013) to
# define the position vector of a sub-Arctic krill.
poly_vec <- c(0.83, 0.36, -2.10, -1.20, 0.63, 0.82, 0.64)
# Create the position vector
# This outputs a list containing "rpos" and "radius"
pos <- polynomial_cylinder(
  length_body = 15e-3, radius_body = 2e-3,
  polynomial = poly_vec
)
str(pos)

Creates a prolate spheroid.

Description

Creates a prolate spheroid.

Usage

prolate_spheroid(
  length_body = NULL,
  radius_body = NULL,
  length_radius_ratio = NULL,
  semimajor_length = NULL,
  semiminor_length = NULL,
  n_segments = 100,
  length_units = "m"
)

Arguments

length_body

Semi-major axis length (m).

radius_body

Semi-minor axis length (m). This can also be stylized as the "maximum radius" of the scattering object.

length_radius_ratio

Optional ratio input when radius is not explicitly known.

semimajor_length

Optional alias for semi-major axis length (m).

semiminor_length

Optional alias for semi-minor axis length (m).

n_segments

Number of segments to discretize object shape. Defaults to 18 segments.

length_units

Units for body matrix (defaults to m).

Value

Creates the position vector for a prolate spheroid object of defined semi-major and -minor axes.

Examples

prolate_spheroid(
  length_body = 0.04, radius_body = 0.004, n_segments = 60
)
prolate_spheroid(
  semimajor_length = 0.05, semiminor_length = 0.003
)

Convert angular measurements from degrees to radians.

Description

Convert angular measurements from degrees to radians.

Usage

radians(x)

Arguments

x

A real value in degrees

Value

Angle in radians.

Examples

orientation <- 90 # degrees
radians(orientation) # this should return a value equal to pi / 2 radians

Re-anchor a stored shape or scatterer component along the x axis

Description

Translate a shape or scatterer component so that its nose, center, or tail lies at a specified x position.

Usage

reanchor_shape(
  object,
  anchor = c("nose", "center", "tail", "max_x", "min_x"),
  at = 0,
  component = NULL,
  containment = c("warn", "error", "ignore")
)

Arguments

object

Shape or Scatterer object.

anchor

Anchor location used to define the translation target. nose is treated as the maximum stored x position and tail as the minimum.

at

Target x location (m).

component

Optional component name for scatterers. Defaults to the primary geometry ("body" for most scatterers and "shell" for ESS).

containment

Containment policy used when a moved swimbladder or backbone is checked against its body: "warn", "error", or "ignore".

Value

The modified object, returned as the same broad object type.

Examples

shape_obj <- prolate_spheroid(length_body = 0.04, radius_body = 0.004)
centered_shape <- reanchor_shape(shape_obj, anchor = "center", at = 0)
range(extract(centered_shape, c("position_matrix", "x")))

Resize or reparameterize a scatterer object

Description

Generic function for rescaling or otherwise reparameterizing an existing scatterer while preserving its class semantics. The class-specific methods handle the component bookkeeping needed to keep the resulting object structurally valid after lengths, widths, heights, shell thicknesses, or related geometry descriptors are changed.

Usage

reforge(object, ...)

Arguments

object

A scatterer object.

...

Additional arguments passed to specific methods.

Details

reforge() is the package's main post-construction geometry-adjustment tool. It is useful when a target should be modified in place rather than rebuilt from scratch. The available method-specific arguments depend on the scatterer class and typically include direct scale factors and/or target dimensions for length, width, or height.

Value

A scatterer of the same broad class as object, rebuilt with the requested geometric changes.

Examples

obj <- fls_generate(
  shape = sphere(radius_body = 0.01, n_segments = 40),
  density_body = 1045,
  sound_speed_body = 1520
)

bigger_obj <- reforge(obj, body_target = c(length = 0.03))
extract(bigger_obj, c("shape_parameters", "length"))

Reforge BBF-class object.

Description

Resize a backboned-fish scatterer by rescaling the flesh body and elastic backbone independently or together. The body follows the same profile-based length/width/height scaling used by SBF, while the backbone retains the same cylinder-style component bookkeeping and preserves its relative axial start within the body when body length changes.

Usage

## S4 method for signature 'BBF'
reforge(
  object,
  body_scale = NULL,
  body_target = NULL,
  backbone_scale = NULL,
  backbone_target = NULL,
  isometric_body = TRUE,
  isometric_backbone = TRUE,
  maintain_ratio = TRUE,
  n_segments_body = NULL,
  n_segments_backbone = NULL,
  containment = c("warn", "error", "ignore")
)

Arguments

object

BBF-class object.

body_scale

Proportional scaling to the body length, width, and height dimensions. When a single value is supplied, all dimensions are scaled uniformly. Otherwise, this input must be a named numeric vector.

body_target

Target dimensions (m) for the body length, width, and height dimensions. This input must be a named numeric vector.

backbone_scale

Proportional scaling to the backbone length, width, and height dimensions. When a single value is supplied, all dimensions are scaled uniformly. Otherwise, this input must be a named numeric vector.

backbone_target

Target dimensions (m) for the backbone length, width, and height dimensions. This input must be a named numeric vector.

isometric_body

Logical; maintain isometric scaling for body.

isometric_backbone

Logical; maintain isometric scaling for backbone.

maintain_ratio

Maintain size ratio between body and backbone.

n_segments_body

Number of points along the body profile.

n_segments_backbone

Number of points along the backbone profile.

containment

Containment policy for internal geometry checks. Use "warn" to keep the current warning behavior, "error" to fail fast for invalid internal geometries, or "ignore" to skip containment checks.

Value

Modified BBF-class object.

Examples

methods::selectMethod("reforge", "BBF")

Reforge CAL-class object

Description

Resize a calibration sphere by applying an isometric scale factor or specifying a target diameter. Optionally re-discretize to a new segment count. CAL objects are always spheres, so the position matrix follows the sphere() convention (n_points x 5: x, y, z, zU, zL).

Usage

## S4 method for signature 'CAL'
reforge(object, scale = NULL, diameter_target = NULL, n_segments = NULL)

Arguments

object

CAL-class object.

scale

Single positive scale factor applied isometrically. Mutually exclusive with diameter_target.

diameter_target

Target sphere diameter (m). Derives the scale factor internally. Mutually exclusive with scale.

n_segments

New number of discrete segments along the major axis.

Value

Modified CAL-class object.

Examples

methods::selectMethod("reforge", "CAL")

Reforge ESS-class object

Description

Resize an elastic-shelled scatterer by applying an isometric scale factor or specifying a target maximum shell radius. Shell thickness can be updated independently, which rescales the fluid body so that the maximum fluid radius equals new_max_shell_radius - shell_thickness (matching the convention in ess_generate). The underlying shape (sphere, prolate spheroid, cylinder, etc.) is preserved for both shell and fluid bodies; scaling is applied uniformly to all axes of each position matrix.

Usage

## S4 method for signature 'ESS'
reforge(
  object,
  scale = NULL,
  radius_target = NULL,
  shell_thickness = NULL,
  n_segments = NULL
)

Arguments

object

ESS-class object.

scale

Single positive scalar applied isometrically to the shell (and fluid body, if present). Mutually exclusive with radius_target.

radius_target

Target maximum outer shell radius (m). Scale factor derived as radius_target / max(current_shell_radius). Mutually exclusive with scale.

shell_thickness

New shell wall thickness (m). The fluid body is rescaled so its maximum radius equals new_max_shell_radius - shell_thickness. Can be combined with scale/radius_target or used alone.

n_segments

New number of discrete segments. All columns of both the shell and fluid position matrices are re-interpolated along the x-axis.

Value

Modified ESS-class object.

Examples

methods::selectMethod("reforge", "ESS")

Reforge FLS-class object

Description

Resize a fluid-like scatterer's single body by scaling its length and/or radius, supplied either as a direct body_scale factor or a body_target dimension (m). The cross-section is circular, so radius drives both lateral and vertical extent together.

Usage

## S4 method for signature 'FLS'
reforge(
  object,
  body_scale = NULL,
  body_target = NULL,
  isometric_body = TRUE,
  n_segments_body = NULL,
  length = NULL,
  radius = NULL,
  length_radius_ratio_constant = TRUE,
  n_segments = NULL
)

Arguments

object

FLS-class object.

body_scale

Proportional scaling to the body length and radius. When a single value is supplied, both dimensions are scaled together. Otherwise, this input must be a named numeric vector using length and/or radius.

body_target

Target dimensions (m) for the body length and/or radius. This input must be a named numeric vector.

isometric_body

Logical; maintain isometric scaling for body.

n_segments_body

New number of segments along the body profile.

length

Legacy alias for a new body length resize.

radius

Legacy alias for a new maximum body radius.

length_radius_ratio_constant

Legacy toggle controlling whether a length-only resize also rescales radius.

n_segments

Legacy alias for n_segments_body.

Details

For bent bodies (see brake()) a length resize follows the true centerline arc length and rescales the curved path, while a radius resize changes only the tube thickness and leaves the centerline in place. The legacy length, radius, length_radius_ratio_constant, and n_segments arguments are retained as thin wrappers over the body_scale/body_target pathway.

Value

An updated object of class FLS.

Examples

methods::selectMethod("reforge", "FLS")

Reforge GAS-class object

Description

Resize a gas-filled fluid scatterer. GAS bodies are single-component fluid-like targets, so the interface mirrors reforge() for FLS: supply either a direct body_scale or a body_target describing the desired length and/or radius. Because both dimensions are addressable, elongated canonical bodies (prolate spheroids, cylinders) can be reshaped non-isometrically - for example lengthening the body while holding its radius fixed.

Usage

## S4 method for signature 'GAS'
reforge(
  object,
  body_scale = NULL,
  body_target = NULL,
  isometric_body = TRUE,
  n_segments_body = NULL,
  scale = NULL,
  radius_target = NULL,
  n_segments = NULL
)

Arguments

object

GAS-class object.

body_scale

Proportional scaling for the body length and/or radius. A single value scales both dimensions isometrically; otherwise supply a named numeric vector using length and/or radius.

body_target

Target dimensions (m) for the body length and/or radius, supplied as a named numeric vector using length and/or radius.

isometric_body

Logical; maintain isometric scaling for the body.

n_segments_body

New number of segments along the body profile.

scale

Legacy isometric scale factor applied to every axis. Mutually exclusive with radius_target.

radius_target

Legacy target maximum body radius (m); the isometric scale factor is derived as radius_target / max(current_radius). Mutually exclusive with scale.

n_segments

Legacy alias for n_segments_body.

Details

When the body is a recognized canonical family (sphere, prolate spheroid, or cylinder) the geometry is regenerated from the requested dimensions through the corresponding shape constructor, which keeps the discretization clean and the stored shape descriptor accurate. Arbitrary shapes fall back to direct per-axis scaling of the position matrix. In every case the returned object is a GAS, with the internal-gas material contrasts, orientation, and metadata preserved.

The legacy scale, radius_target, and n_segments arguments remain available and are isometric: they scale every axis together, so a sphere stays a sphere. Use body_scale/body_target for independent length and radius control.

Value

Modified GAS-class object.

Examples

methods::selectMethod("reforge", "GAS")

Reforge SBF-class object

Description

Resize a swimbladdered fish scatterer by rescaling the flesh body and the gas-filled swimbladder together or independently. Body and swimbladder geometry each support length, width, and height scaling supplied as a direct ⁠*_scale⁠ factor or a ⁠*_target⁠ dimension (m).

Usage

## S4 method for signature 'SBF'
reforge(
  object,
  body_scale = NULL,
  body_target = NULL,
  swimbladder_scale = NULL,
  swimbladder_target = NULL,
  isometric_body = TRUE,
  isometric_swimbladder = TRUE,
  maintain_ratio = TRUE,
  swimbladder_inflation_factor = 1,
  n_segments_body = NULL,
  n_segments_swimbladder = NULL,
  containment = c("warn", "error", "ignore")
)

Arguments

object

SBF-class object.

body_scale

Proportional scaling to the body length, width, and height dimensions. When a single value is supplied, all dimensions are scaled using the same scaling factor. Otherwise, this input must be a named numeric vector.

body_target

Target dimensions (m) for the body length, width, and height dimensions. This input must be a named numeric vector.

swimbladder_scale

Proportional scaling to the swimbladder length, width, and height dimensions. When a single value is supplied, all dimensions are scaled using the same scaling factor. Otherwise, this input must be a named numeric vector.

swimbladder_target

Target dimensions (m) for the swimbladder length, width, and height dimensions. This input must be a named numeric vector.

isometric_body

Logical; maintain isometric scaling for body.

isometric_swimbladder

Logical; maintain isometric scaling for bladder.

maintain_ratio

Maintain size ratio between body and swimbladder.

swimbladder_inflation_factor

Proportional swimbladder volume where the swimbladder x-axis origin and terminus are both held constant.

n_segments_body

Number of segments along the body.

n_segments_swimbladder

Number of segments along the bladder.

containment

Containment policy for internal geometry checks. Use "warn" to keep the current warning behavior, "error" to fail fast for invalid internal geometries, or "ignore" to skip containment checks.

Details

Vertical scaling is applied about each component's own centerline so that curved bodies keep their proportions when resized rather than warping - a resized body remains geometrically similar whether it is enlarged or shrunk. After scaling, the swimbladder is re-nested inside the body: its relative along-body start and its relative vertical offset within the body envelope are restored, so the bladder tracks the body instead of drifting out of it. The swimbladder_inflation_factor scales only the bladder width and height (its length endpoints are held fixed) about the bladder's own center. The containment policy governs what happens when the swimbladder exceeds the body envelope.

Value

An updated object of class SBF.

Examples

methods::selectMethod("reforge", "SBF")

Register a user-defined target-strength model

Description

Usage

register_model(
  name,
  initialize,
  solver,
  slot = NULL,
  aliases = character(),
  persist = FALSE,
  overwrite = FALSE
)

Arguments

name

Canonical model name passed to target_strength().

initialize

Initializer function or function reference.

solver

Solver function or function reference.

slot

Result-slot name stored on the scatterer. Defaults to the usual upper-case model label derived from name.

aliases

Optional alternative model names.

persist

Logical scalar. When TRUE, the model registration is written to the user's R_user_dir() config path and reloaded in later sessions. Persistent registrations require package-qualified function references such as "mypkg::tsl_initialize" and "mypkg::TSL".

overwrite

Logical scalar. When TRUE, an existing user registration with the same canonical name can be replaced. Built-in models cannot be overwritten.

Value

Invisibly returns the normalized registry entry.

Examples

if (interactive()) {
  initialize_demo <- function(object, frequency, ...) object
  solve_demo <- function(object) object
  register_model(
    "demo",
    initialize = initialize_demo,
    solver = solve_demo
  )
  unregister_model("demo")
}

Resample a stored shape or scatterer profile to a new segment count

Description

Re-discretize a shape or scatterer component along its x axis without rebuilding it from scratch.

Usage

resample_shape(
  object,
  n_segments,
  component = NULL,
  containment = c("warn", "error", "ignore")
)

Arguments

object

Shape or Scatterer object.

n_segments

New number of intervals used to discretize the profile.

component

Optional component name for scatterers. Defaults to the primary geometry ("body" for most scatterers and "shell" for ESS).

containment

Containment policy used when a moved swimbladder or backbone is checked against its body: "warn", "error", or "ignore".

Value

The modified object, returned as the same broad object type.

Examples

shape_obj <- sphere(radius_body = 0.01, n_segments = 20)
shape_fine <- resample_shape(shape_obj, n_segments = 80)
extract(shape_fine, c("shape_parameters", "n_segments"))

Clear user-defined model registrations

Description

Clear user-defined model registrations

Usage

reset_model_registry(remove_persisted = FALSE)

Arguments

remove_persisted

Logical scalar. When TRUE, persisted user model registrations are also deleted from the user's config file.

Value

Invisibly returns NULL.

Examples

if (interactive()) {
  reset_model_registry()
}

Calculate the density contrast (`\rho`) of a scattering boundary

Description

Calculate the density contrast (\rho) of a scattering boundary

Usage

rho(medium, target)

Arguments

medium

Dataframe object containing density (kgm^{-3}) and sound speed (ms^{-1}) values for the external medium.

target

Dataframe object containing density (kgm^{-3}) and sound speed (ms^{-1}) values for the target boundary.

Value

Density contrast, defined as (\rho_{target} - \rho_{medium})/\rho_{target}.

Examples

seawater <- data.frame(density = 1026, sound_speed = 1480)
animal <- data.frame(density = 1050, sound_speed = 1530)
rho(seawater, animal)

Sample sardine shape with fully inflated swimbladder

Description

A pre-generated SBF scatterer containing all information required for target strength modeling. The packaged geometry follows the sardine entry distributed through the NOAA Fisheries KRM reference collection and archived in the echoSMs resources. The object metadata identifies the target as Sardinops sagax caerulea following Conti and Demer (2003).

Usage

data(sardine)

Format

A named list with the following components:

metadata

Relevant and identifying metadata (list).

model_parameters

Specified model parameters (list).

model

Model outputs and results (list).

body

A list with:

rpos: Position matrix (x, yw, zU, zL; m).
sound_speed: Flesh sound speed (c_{body}, m/s).
density: Flesh density (\rho_{body}, kg/m^3).
theta: Orientation relative to transducer (\theta_{body}, radians).

bladder

A list with:

rpos: Position matrix (x, yw, zU, zL; m).
sound_speed: Bladder sound speed (c_{bladder}, m/s).
density: Bladder density (\rho_{bladder}, kg/m^3).
theta: Orientation relative to transducer (\theta_{bladder}, radians).

shape_parameters

A named list with:

body: A list describing the body:
- length: Body length (m).
- ncyl: Number of discrete cylinders.
- theta_units: Units for orientation angle.
- length_units: Units for length.
bladder: A list describing the swimbladder:
- length: Bladder length (m).
- ncyl: Number of discrete cylinders.
- theta_units: Units for orientation angle.
- length_units: Units for length.

Value

A pre-generated SBF scatterer object.

Source

NOAA Fisheries KRM model reference collection (https://www.fisheries.noaa.gov/data-tools/krm-model) and the archived echoSMs resource set (https://github.com/ices-tools-dev/echoSMs).

References

Conti, S.G., and Demer, D.A. (2003). Wide-bandwidth acoustical characterization of anchovy and sardine from reverberation measurements in an echoic tank. ICES Journal of Marine Science, 60, 617-624. doi:10.1016/S1054-3139(03)00056-0

Examples

data("sardine", package = "acousticTS")
sardine

Generate a SBF-class object.

Description

Generate a SBF-class object.

Usage

sbf_generate(
  x_body = NULL,
  w_body = NULL,
  zU_body = NULL,
  zL_body = NULL,
  x_bladder = NULL,
  w_bladder = NULL,
  zU_bladder = NULL,
  zL_bladder = NULL,
  sound_speed_body = NULL,
  sound_speed_bladder = NULL,
  g_body = NULL,
  h_body = NULL,
  g_bladder = NULL,
  h_bladder = NULL,
  density_body = NULL,
  density_bladder = NULL,
  theta_body = pi/2,
  theta_bladder = pi/2,
  theta_units = "radians",
  length_units = "m",
  ID = NULL,
  body_shape = NULL,
  bladder_shape = NULL
)

Arguments

x_body

Vector containing along-body axis (m).

w_body

Vector containing across-body axis (m).

zU_body

Vector containing dorsal-body axis (m).

zL_body

Vector containing ventral-body axis (m).

x_bladder

Vector containing along-bladder axis (m).

w_bladder

Vector containing across-bladder axis (m).

zU_bladder

Vector containing dorsal-bladder axis (m).

zL_bladder

Vector containing ventral-bladder axis (m).

sound_speed_body

Flesh sound speed (c;_body, m s^-1).

sound_speed_bladder

Bladder sound speed (c, m s^-1).

g_body

Body density contrast.

h_body

Body sound speed contrast.

g_bladder

Bladder density contrast.

h_bladder

Bladder sound speed contrast.

density_body

Flesh density (ρ_body, kg m³).

density_bladder

Bladder density (\rho, kg m³).

theta_body

Angle of body relative to wavefront (\theta_body, radians).

theta_bladder

Angle of bladder relative to wavefront (\theta_bladder, radians).

theta_units

Compatibility argument. Scatterer constructors now assume radians and ignore non-SI alternatives.

length_units

Compatibility argument. Scatterer constructors now assume meters and ignore non-SI alternatives.

ID

Optional metadata identifier.

body_shape

Optional pre-built Shape for the body; overrides x_body/w_body/zU_body/zL_body if supplied.

bladder_shape

Optional pre-built Shape for the bladder; overrides x_bladder/w_bladder/zU_bladder/zL_bladder if supplied.

Details

The recommended interface is to supply pre-built Shape objects through body_shape and bladder_shape, then specify material properties through either contrasts (⁠g_*⁠, ⁠h_*⁠) or absolute density/sound-speed values. Legacy coordinate-vector inputs are retained for backward compatibility and are converted internally to Shape objects before the scatterer is built. Character-based shape dispatch is deprecated; build the component geometry first with a Shape constructor and then pass the resulting Shape object.

Body/bladder width vectors (w_body, w_bladder) default to zeros when missing. Resulting rpos matrices always carry the row names x_body, w_body, zU_body, zL_body for the body and x_bladder, w_bladder, zU_bladder, zL_bladder for the bladder.

Value

Generates a SBF-class object.

Examples

# Manual body/bladder coordinates
sbf_generate(
  x_body = seq(0, 0.1, length.out = 5),
  w_body = rep(0, 5),
  zU_body = seq(0.001, 0.002, length.out = 5),
  zL_body = -seq(0.001, 0.002, length.out = 5),
  x_bladder = seq(0.02, 0.09, length.out = 4),
  w_bladder = rep(0, 4),
  zU_bladder = rep(0.0015, 4),
  zL_bladder = rep(-0.0015, 4),
  sound_speed_body = 1500,
  sound_speed_bladder = 340,
  density_body = 1040,
  density_bladder = 1.2
)

# Using pre-built shapes
body_shape <- arbitrary(
  x_body = c(0, 0.1), zU_body = c(0.001, 0.002),
  zL_body = c(-0.001, -0.002)
)
bladder_shape <- arbitrary(
  x_bladder = c(0.02, 0.09), w_bladder = c(0, 0),
  zU_bladder = c(0.0015, 0.0015),
  zL_bladder = c(-0.0015, -0.0015)
)
sbf_generate(
  body_shape = body_shape, bladder_shape = bladder_shape,
  sound_speed_body = 1500, sound_speed_bladder = 340,
  density_body = 1040, density_bladder = 1.2
)

Calculate the shear modulus (G)

Description

Calculates the shear modulus (G) from two of the three other elastic moduli: bulk modulus (K), Young's modulus (E), or Poisson's ratio (\nu). Assumes 3D material properties.

The relationships used are:

G = \frac{3KE}{9K - E}

G = \frac{3K(1 - 2\nu)}{2(1 + \nu)}

G = \frac{E}{2(1 + \nu)}

Usage

shear(K = NULL, E = NULL, nu = NULL)

Arguments

K

Bulk modulus (Pa).

E

Young's modulus (Pa).

nu

Poisson's ratio (Dimensionless).

Value

Shear modulus (G, Pa).

Examples

shear(K = 2.5e9, E = 3e9)

Display a scatterer object

Description

Display a scatterer object

Usage

## S4 method for signature 'Scatterer'
show(object)

Arguments

object

Scattering object.

Value

Called for its side effect of printing a formatted summary; invisibly returns NULL.

Examples

show(cal_generate(material = "WC", n_segments = 20))

Simulate target strength (TS) with flexible parameterization and batching

Description

Simulate target strength (TS) with flexible parameterization and batching

Usage

simulate_ts(
  object,
  frequency,
  model,
  n_realizations = NULL,
  parameters = list(),
  batch_by = NULL,
  permute = TRUE,
  parallel = TRUE,
  n_cores = .default_simulation_cores(),
  verbose = TRUE
)

Arguments

object

Scatterer-class object.

frequency

Frequency (Hz).

model

Model name. If multiple models are specified, the output will be a list of data frames, one for each model.

n_realizations

Optional number of repeated evaluations of each deterministic grid cell (default 1). It is a pure repeat/redraw multiplier: every deterministic multi-value parameter is always treated as a grid axis, and n_realizations controls how many times each resulting cell is evaluated, redrawing any generating functions each time. The total number of realizations is therefore the size of the Cartesian grid multiplied by n_realizations (for example, one length and two radii yield two cells; with n_realizations = 5 that is ten realizations). Use it to draw repeated samples from generating functions (distributions).

parameters

List containing the values, distributions, or generating functions of parameter values that inform the TS model. Defaults to an empty list, which runs a single realization of the unmodified object.

batch_by

Optional. Specifies which parameters in parameters to batch over. Simulations will be run for all combinations of these parameter values. Default is NULL.

permute

Logical; controls how varied parameters combine. When TRUE (default) every deterministic multi-value parameter is crossed into the full Cartesian grid. When FALSE the varied parameters are instead paired (zipped) element-wise, so they advance together rather than combinatorially; in that case every varied parameter must supply the same number of values (length-one parameters are held constant).

parallel

Logical; whether to parallelize the simulations. Default is TRUE.

n_cores

Optional. Number of CPU cores to use for parallelization. Default is the smaller of 2 cores and parallel::detectCores() - 1.

verbose

Logical; whether to print progress and status messages to the console. Default is TRUE.

Details

simulate_ts() is a workflow wrapper around repeated target_strength() calls. It supports three broad parameter modes inside parameters:

scalars that are recycled across every realization,
explicit vectors that are either aligned with the full simulation grid or with one or more batched dimensions, and
generating functions that are re-evaluated for each realization, and
structured values such as named target-dimension vectors used by reforge() (for example body_target = c(length = 0.03)).

If batch_by = "length" and parameters[["length"]] is a vector of candidate values, then simulations are run for each length value, repeated n_realizations times. When multiple parameters are supplied through batch_by, the function builds the full Cartesian grid of those parameter values and runs the requested number of realizations inside each batch cell.

Batching is automatic and follows one consistent rule: every deterministic multi-value parameter is a grid axis, whether or not n_realizations or batch_by are supplied. A bare vector therefore always means "sweep these values" rather than "align one value per realization". batch_by remains available to document intent, but naming an axis is no longer required for it to be swept.

To vary parameters together (paired rather than crossed) set permute = FALSE. The varied parameters are then zipped element-wise and must share the same number of values. For example, parameters = list(theta_body = c(1, 2), density_body = c(1040, 1050)) yields four runs by default but two paired runs - (1, 1040) and (2, 1050) - under permute = FALSE. Alternatively, values that belong to one reforge() target can be paired within a single structured parameter, for example parameters = list(body_target = list(c(length = 0.02, radius = 0.002), c(length = 0.03, radius = 0.003))).

Structured batch values should be wrapped in a list so that each candidate is preserved as one unit. For example, use parameters = list(body_target = list(c(length = 0.02), c(length = 0.03)))) when batching across multiple explicit reforge() targets.

Convenience dimension aliases are also supported for compatible reforge() methods. For example, length_body = 0.03 is treated the same as body_target = c(length = 0.03) for fluid-like scatterers, while retaining the original length_body column in the returned simulation output.

Parameter names are interpreted in the same way they would be if supplied directly to target_strength() or to the relevant object constructor / reforge() path. This means simulate_ts() can be used for:

orientation perturbations,
material-property perturbations,
morphology studies that trigger shape rebuilding or reforging, and
side-by-side comparisons across one or more model families.

Value

A data frame when a single model is requested, or a named list of data frames when multiple models are requested. Each returned data frame contains the realized parameter values together with the modeled acoustic output for each simulated run.

Parallelization

This function uses pbapply::pblapply() for parallelized simulation with progress bars. The current implementation uses PSOCK clusters for worker execution across platforms, including Windows, macOS, and Linux. That means worker processes need access to the package namespace and any required exported objects, and it also means startup overhead is more noticeable for very small simulation jobs than for larger batched runs.

Performance Issues

Including too many parameters from parameters within batch_by may cause significant performance issues or cause R to crash. If intensive simulations are required, consider breaking them into more manageable chunks

Examples

shape_obj <- cylinder(
  length_body = 0.05,
  radius_body = 0.003,
  n_segments = 40
)

obj <- fls_generate(
  shape = shape_obj,
  density_body = 1045,
  sound_speed_body = 1520
)

res <- simulate_ts(
  object = obj,
  frequency = seq(38e3, 50e3, by = 6e3),
  model = "dwba",
  n_realizations = 2,
  parameters = list(
    theta_body = function() runif(1, min = 0.5 * pi, max = pi),
    density_body = 1045
  ),
  parallel = FALSE,
  verbose = FALSE
)

head(res)

Smooth a stored shape or scatterer profile

Description

Smooth the stored geometry using a centered moving-average filter applied to profile coordinates. This is useful for cleaning digitized outlines before canonicalization or model runs. For canonical Shape objects, the result is returned as an Arbitrary shape because the edited profile is no longer guaranteed to preserve the canonical class geometry.

Usage

smooth_shape(
  object,
  span = 5,
  component = NULL,
  preserve_ends = TRUE,
  containment = c("warn", "error", "ignore")
)

Arguments

object

Shape or Scatterer object.

span

Centered moving-average span. Even values are rounded up to the next odd integer.

component

Optional component name for scatterers. Defaults to the primary geometry ("body" for most scatterers and "shell" for ESS).

preserve_ends

Logical; whether to keep the first and last profile points fixed.

containment

Containment policy used when a moved swimbladder or backbone is checked against its body: "warn", "error", or "ignore".

Value

The modified object. Shape inputs that are smoothed are returned as Arbitrary shapes.

Examples

shape_obj <- arbitrary(
  x_body = c(0, 0.01, 0.02, 0.03, 0.04),
  zU_body = c(0, 0.003, 0.006, 0.0035, 0),
  zL_body = c(0, -0.0025, -0.0055, -0.003, 0)
)
smoothed_shape <- smooth_shape(shape_obj, span = 3)
extract(smoothed_shape, c("shape_parameters", "n_segments"))

Creates a sphere.

Description

Creates a sphere.

Usage

sphere(radius_body, n_segments = 100, diameter_units = "m")

Arguments

radius_body

Object radius (m).

n_segments

Number of segments to discretize object shape. Defaults to 1e2 segments.

diameter_units

Default is "m" for meters

Value

Creates position vector for a spherical object of a defined radius.

Examples

sphere(radius_body = 0.01, n_segments = 50)

Wrapper function to model acoustic target strength

Description

Wrapper function to model acoustic target strength

Usage

target_strength(
  object,
  frequency,
  model,
  verbose = FALSE,
  model_args = NULL,
  ...
)

Arguments

object

Scatterer-class object.

frequency

Frequency (Hz).

model

Model name. Available models currently include "dwba" (DWBA), "bbfm" (BBFM), "pcdwba" (PCDWBA), "sdwba" (SDWBA), "fcms" (FCMS), "bcms" (BCMS), "ecms" (ECMS), "hpa" (HPA), "krm" (KRM), "psms" (PSMS), "sphms" (SPHMS), "essms" (ESSMS), "vesms" (VESMS), "trcm" (TRCM), and "calibration" / "soems" (SOEMS).

verbose

Prints current procedural step occurring from model initialization to calculating TS. Defaults to FALSE.

model_args

Optional named list of per-model argument bundles. Each list name should match one of the requested model names case-insensitively, and each value should be either a named list or a named atomic vector of arguments to apply only to that model. When the same argument is supplied both through ... and through model_args[[model_name]], the model-specific entry takes precedence.

...

Additional optional model inputs/parameters.

Details

This is the main high-level entry point for running target-strength models in acousticTS. The supplied scatterer object is checked, the requested model or models are initialized, and the resulting outputs are stored back on the same object.

The available model families span exact modal-series solutions and approximation-based solutions. Readers should consult the model-specific help topics for the physical assumptions, valid object types, boundary-condition options, and model-specific arguments used by each implementation:

DWBA for the distorted-wave Born approximation applied to weakly scattering fluid-like bodies.
BBFM for a composite flesh-plus-backbone model that combines a DWBA flesh term with an elastic-cylinder backbone term.
PCDWBA for the phase-compensated distorted-wave Born approximation applied to elongated fluid-like bodies.
SDWBA for the stochastic distorted-wave Born approximation.
FCMS for the finite cylinder modal series solution.
BCMS for the bent-cylinder modal series solution.
ECMS for the elastic-cylinder modal series solution.
HPA for the high-pass approximation family.
KRM for the Kirchhoff-Ray Mode model.
PSMS for the prolate spheroidal modal series solution.
SPHMS for the spherical modal series solution.
ESSMS for the elastic-shelled spherical modal series solution.
VESMS for the viscous-elastic spherical scattering model applied to gas-filled elastic shells with an external viscous layer.
TMM for the single-target transition-matrix family.
TRCM for the two-ray cylindrical model.
SOEMS for the solid elastic calibration-sphere model, accessed through "calibration" or "soems".

Model-specific inputs are usually passed through .... For example, some models require a boundary argument, HPA uses a method argument, and several models expose additional numerical controls. When several models are requested together, shared arguments may be supplied through ... and per-model overrides may be supplied through model_args. This is useful when different models should share the same seawater properties but only one of them needs an extra stochastic or numerical control:

target_strength(
  object,
  frequency,
  model = c("dwba", "sdwba"),
  density_sw = 1026,
  sound_speed_sw = 1478,
  model_args = list(
    sdwba = list(phase_sd_init = 0.77)
  )
)

Model names are normalized internally, so case-insensitive inputs such as "DWBA" and "dwba" resolve to the same family.

Value

The input scatterer object with requested model parameters, model outputs, and target strength results stored in its model slots.

Examples

calibration_sphere <- cal_generate(
  material = "WC",
  diameter = 38.1e-3,
  n_segments = 40
)
target_strength(
  calibration_sphere,
  frequency = c(38e3, 120e3),
  model = "calibration"
)

Orientation-average scattering from a stored TMM object

Description

Reuses the stored TMM blocks to average the differential scattering cross section over a user-supplied set of incident orientations. By default the receive direction is taken to be the exact monostatic direction for each supplied orientation.

Usage

tmm_average_orientation(
  object,
  theta_body = NULL,
  weights = NULL,
  phi_body = pi,
  theta_scatter = NULL,
  phi_scatter = NULL,
  distribution = NULL
)

Arguments

object

Scatterer-object previously evaluated with target_strength(..., model = "TMM", store_t_matrix = TRUE).

theta_body

Numeric vector of incident polar angles (radians).

weights

Optional numeric vector of averaging weights. When omitted, equal weights are used.

phi_body

Incident azimuth angle(s) (radians). Either scalar or the same length as theta_body. Defaults to pi.

theta_scatter

Receive polar angle(s) (radians). Either scalar or the same length as theta_body. Defaults to the monostatic direction.

phi_scatter

Receive azimuth angle(s) (radians). Either scalar or the same length as theta_body. Defaults to the monostatic direction.

distribution

Optional orientation distribution created by tmm_orientation_distribution. When supplied, it overrides the direct theta_body, weights, and phi_body inputs.

Value

A data frame containing the frequency, the orientation-averaged differential backscattering cross section and the corresponding orientation-averaged target strength.

Examples

target <- fls_generate(
  shape = sphere(radius_body = 0.005, n_segments = 20),
  g_body = 1,
  h_body = 1
)
stored <- target_strength(
  target,
  frequency = 12e3,
  model = "tmm",
  boundary = "pressure_release",
  store_t_matrix = TRUE
)
distribution <- tmm_orientation_distribution(n_theta = 5)
tmm_average_orientation(stored, distribution = distribution)

Summarize bistatic products from a stored TMM object

Description

Reuses the stored T-matrix blocks at one stored frequency to compute a higher-level bistatic summary, including forward- and cross-plane slices, peak-scattering direction, backscatter-lobe width, and integrated scattering over coarse angular sectors. In the current package build, this helper is available for the spherical and spheroidal stored branches. Stored cylinders intentionally stop at exact monostatic reuse until a validated retained cylinder angular operator is added.

Usage

tmm_bistatic_summary(
  object,
  frequency = NULL,
  theta_body = NULL,
  phi_body = NULL,
  n_theta = 91,
  n_phi = 181,
  n_psi = 181,
  sectors = NULL,
  drop_dB = 3,
  include_grid = FALSE
)

Arguments

object

Scatterer-object previously evaluated with target_strength(..., model = "TMM", store_t_matrix = TRUE).

frequency

Stored frequency (Hz) to summarize. Required when the object contains more than one stored frequency.

theta_body

Incident polar angle (radians). Defaults to the stored TMM incident angle.

phi_body

Incident azimuth angle (radians). Defaults to the stored TMM incident angle.

n_theta

Number of receive polar-angle samples used by the summary grid.

n_phi

Number of receive azimuth samples used by the summary grid.

n_psi

Number of forward-centered angular samples used for the local great-circle slices.

sectors

Optional data frame with columns sector, psi_min, and psi_max (radians). When omitted, three coarse forward/oblique/backward sectors are used.

drop_dB

Positive dB drop used to define the backscatter-lobe width on the forward-centered slice.

include_grid

Logical; include the underlying scattering grid in the returned list.

Value

A list containing scalar summary metrics, the named slice data frames, sector integrals, and optionally the underlying scattering grid.

Examples

target <- fls_generate(
  shape = sphere(radius_body = 0.005, n_segments = 20),
  g_body = 1,
  h_body = 1
)
stored <- target_strength(
  target,
  frequency = 12e3,
  model = "tmm",
  boundary = "pressure_release",
  store_t_matrix = TRUE
)
tmm_bistatic_summary(
  stored,
  n_theta = 5,
  n_phi = 9,
  n_psi = 9
)

Diagnostics for stored single-target TMM solutions

Description

Reuses the stored transition-matrix blocks to compute a compact set of numerical and physics-based diagnostics for one or more stored frequencies. The summary combines:

monostatic reconstruction residuals,
reciprocity residuals under incident/receive-angle exchange,
an optical-theorem residual based on forward scattering and the integrated differential cross section,
block-level conditioning indicators from the stored transition-matrix blocks,
and, for prolate/oblate targets, an equal-volume sphere-to-spheroid continuation path that checks whether the monostatic response deforms smoothly away from the exact sphere limit.

These checks are meant to help distinguish "the post-processing is self-consistent" from "the retained solve was also numerically comfortable," which is especially helpful for the newer nonspherical TMM branches. For stored cylinders, the current diagnostics are intentionally limited to exact monostatic reconstruction because a validated retained cylinder angular operator is not yet available.

Usage

tmm_diagnostics(
  object,
  frequency = NULL,
  theta_body = NULL,
  phi_body = NULL,
  reciprocity_pairs = NULL,
  n_theta = 61,
  n_phi = 121,
  continuation_steps = 6L
)

Arguments

object

Scatterer-object previously evaluated with target_strength(..., model = "TMM", store_t_matrix = TRUE).

frequency

Optional stored frequency or vector of stored frequencies (Hz). Defaults to all stored frequencies.

theta_body

Incident polar angle (radians) used for the monostatic and optical-theorem checks. Defaults to the stored TMM incident angle.

phi_body

Incident azimuth angle (radians) used for the monostatic and optical-theorem checks. Defaults to the stored TMM incident angle.

reciprocity_pairs

Optional data frame giving explicit reciprocity test angles. Must contain theta_body, phi_body, theta_scatter, and phi_scatter columns in radians.

n_theta

Number of polar-angle grid points used by the optical-theorem integration check.

n_phi

Number of azimuth-angle grid points used by the optical-theorem integration check.

continuation_steps

Number of equal-volume aspect-ratio steps used for the sphere-to-spheroid continuation check on prolate and oblate targets. Set to 0 or 1 to skip the continuation path. Ignored for non-spheroidal targets.

Value

A list with components:

summary: Per-frequency diagnostic summary.
block_metrics: Per-frequency block-level conditioning and transpose-residual summaries.
continuation: Equal-volume sphere-to-spheroid continuation path for spheroidal targets, or NULL for other shapes.

Examples

target <- fls_generate(
  shape = sphere(radius_body = 0.005, n_segments = 20),
  g_body = 1,
  h_body = 1
)
stored <- target_strength(
  target,
  frequency = 12e3,
  model = "tmm",
  boundary = "pressure_release",
  store_t_matrix = TRUE
)
tmm_diagnostics(stored, n_theta = 5, n_phi = 9)

Build an orientation distribution for stored TMM post-processing

Description

Creates a validated set of incident angles and normalized weights that can be reused by tmm_average_orientation or tmm_products. The distributions defined here are distributions in theta_body itself rather than isotropic solid-angle distributions.

Usage

tmm_orientation_distribution(
  distribution = c("uniform", "normal", "truncated_normal", "quadrature", "pdf"),
  theta_body = NULL,
  weights = NULL,
  pdf = NULL,
  phi_body = pi,
  mean_theta = pi/2,
  sd_theta = pi/12,
  lower = 0,
  upper = pi,
  n_theta = 91
)

Arguments

distribution

Orientation-distribution type. One of "uniform", "normal", "truncated_normal", "quadrature", or "pdf".

theta_body

Optional numeric vector of incident polar angles (radians). Required for the "quadrature" and "pdf" pathways.

weights

Optional numeric quadrature weights paired with theta_body for distribution = "quadrature".

pdf

Optional user-supplied density over theta_body for distribution = "pdf". This can be either a numeric vector the same length as theta_body or a function evaluated at theta_body.

phi_body

Incident azimuth angle(s) (radians). Either scalar or the same length as the resolved theta_body grid.

mean_theta

Mean angle (radians) for the normal-family distributions.

sd_theta

Standard deviation (radians) for the normal-family distributions.

lower

Lower bound (radians) for the uniform and truncated-normal distributions.

upper

Upper bound (radians) for the uniform and truncated-normal distributions.

n_theta

Number of grid points for the analytic distributions.

Value

A data frame with normalized orientation weights and class "TMMOrientationDistribution".

Examples

tmm_orientation_distribution(
  distribution = "uniform",
  lower = pi / 3,
  upper = 2 * pi / 3,
  n_theta = 7
)

Collect multiple post-processed products from one stored TMM solve

Description

Provides a higher-level convenience interface for the stored-block TMM workflow. One call can return the monostatic scattering spectrum, an orientation average, and a higher-level bistatic summary without rebuilding the underlying T-matrix solve. For stored cylinders, the currently supported products are the exact monostatic scattering spectrum and the corresponding orientation-averaged monostatic outputs; cylinder bistatic summaries remain unavailable until a validated retained cylinder angular operator is added.

Usage

tmm_products(
  object,
  frequency = NULL,
  theta_body = NULL,
  phi_body = NULL,
  orientation = NULL,
  bistatic_summary = FALSE,
  include_grid = FALSE,
  n_theta = 91,
  n_phi = 181,
  n_psi = 181,
  sectors = NULL,
  drop_dB = 3
)

Arguments

object

Scatterer-object previously evaluated with target_strength(..., model = "TMM", store_t_matrix = TRUE).

frequency

Stored frequency (Hz) used when bistatic_summary = TRUE.

theta_body

Incident polar angle (radians) for the monostatic and bistatic products. Defaults to the stored TMM incident angle.

phi_body

Incident azimuth angle (radians) for the monostatic and bistatic products. Defaults to the stored TMM incident angle.

orientation

Optional orientation distribution created by tmm_orientation_distribution.

bistatic_summary

Logical; include the output of tmm_bistatic_summary.

include_grid

Logical; keep the 2D scattering grid inside the bistatic summary output.

n_theta

Number of receive polar-angle samples for the bistatic summary.

n_phi

Number of receive azimuth samples for the bistatic summary.

n_psi

Number of forward-centered angular samples used by the local summary slices.

sectors

Optional angular-sector table passed to tmm_bistatic_summary.

drop_dB

Positive dB drop used to define the backscatter-lobe width.

Value

A named list containing the requested post-processed TMM products.

Examples

target <- fls_generate(
  shape = sphere(radius_body = 0.005, n_segments = 20),
  g_body = 1,
  h_body = 1
)
stored <- target_strength(
  target,
  frequency = 12e3,
  model = "tmm",
  boundary = "pressure_release",
  store_t_matrix = TRUE
)
tmm_products(stored)

Evaluate scattering from a stored TMM object

Description

Evaluates the far-field scattering amplitude from a previously computed TMM object using the stored transition-matrix blocks. This allows the same retained modal operator to be reused for arbitrary single-target incident and receive-angle combinations without rebuilding the boundary solve.

Usage

tmm_scattering(
  object,
  theta_body = NULL,
  phi_body = NULL,
  theta_scatter = NULL,
  phi_scatter = NULL
)

Arguments

object

Scatterer-object previously evaluated with target_strength(..., model = "TMM", store_t_matrix = TRUE).

theta_body

Incident polar angle (radians). Defaults to the stored TMM incident angle.

phi_body

Incident azimuth angle (radians). Defaults to the stored TMM incident angle.

theta_scatter

Receive polar angle (radians). Defaults to the exact monostatic direction, pi - theta_body.

phi_scatter

Receive azimuth angle (radians). Defaults to the exact monostatic direction, phi_body + pi.

Value

A data frame with the frequency, complex scattering amplitude, the corresponding differential cross section, and its level in dB.

Examples

target <- fls_generate(
  shape = sphere(radius_body = 0.005, n_segments = 20),
  g_body = 1,
  h_body = 1
)
stored <- target_strength(
  target,
  frequency = 12e3,
  model = "tmm",
  boundary = "pressure_release",
  store_t_matrix = TRUE
)
tmm_scattering(stored)

Evaluate a 2D scattering grid from a stored TMM object

Description

Reuses the stored T-matrix blocks to evaluate the far-field scattering response over a two-dimensional receive-angle grid at one stored frequency. This is useful for bistatic scattering maps, heatmaps, and polar-style visualizations without rebuilding the retained modal solve. In the current package build, this helper is available for the spherical and spheroidal stored branches. Stored cylinders intentionally stop at exact monostatic reuse until a validated retained cylinder angular operator is added.

Usage

tmm_scattering_grid(
  object,
  frequency = NULL,
  theta_body = NULL,
  phi_body = NULL,
  theta_scatter = NULL,
  phi_scatter = NULL,
  n_theta = 91,
  n_phi = 181
)

Arguments

object

Scatterer-object previously evaluated with target_strength(..., model = "TMM", store_t_matrix = TRUE).

frequency

Stored frequency (Hz) to evaluate. Required when the object contains more than one stored frequency.

theta_body

Incident polar angle (radians). Defaults to the stored TMM incident angle.

phi_body

Incident azimuth angle (radians). Defaults to the stored TMM incident angle.

theta_scatter

Optional vector of receive polar angles (radians). Defaults to an evenly spaced grid on ⁠[0, pi]⁠.

phi_scatter

Optional vector of receive azimuth angles (radians). Defaults to an evenly spaced grid on ⁠[0, 2*pi]⁠.

n_theta

Number of default polar-angle grid points when theta_scatter is not supplied.

n_phi

Number of default azimuth grid points when phi_scatter is not supplied.

Value

A list containing the stored frequency, the incident angles used to build the grid, the receive-angle vectors, and matrices for the complex scattering amplitude, differential scattering cross section, and its level in dB.

Examples

target <- fls_generate(
  shape = sphere(radius_body = 0.005, n_segments = 20),
  g_body = 1,
  h_body = 1
)
stored <- target_strength(
  target,
  frequency = 12e3,
  model = "tmm",
  boundary = "pressure_release",
  store_t_matrix = TRUE
)
tmm_scattering_grid(stored, n_theta = 5, n_phi = 9)

Translate a stored shape or scatterer component

Description

Shift a Shape object or one geometry-bearing component of a Scatterer without rebuilding it from scratch. This is most useful for re-centering profiles, aligning a stored body to a preferred axial origin, or nudging an internal component before model comparisons.

Usage

translate_shape(
  object,
  x_offset = 0,
  y_offset = 0,
  z_offset = 0,
  component = NULL,
  containment = c("warn", "error", "ignore")
)

Arguments

object

Shape or Scatterer object.

x_offset

Along-axis translation (m).

y_offset

Lateral translation (m). This is ignored for profile-style geometries that do not store an explicit lateral centerline.

z_offset

Vertical translation (m).

component

Optional component name for scatterers. Defaults to the primary geometry ("body" for most scatterers and "shell" for ESS).

containment

Containment policy used when a moved swimbladder or backbone is checked against its body: "warn", "error", or "ignore".

Value

The modified object, returned as the same broad object type.

Examples

shape_obj <- cylinder(
  length_body = 0.05, radius_body = 0.003,
  n_segments = 40
)
moved_shape <- translate_shape(shape_obj, x_offset = 0.01)
range(extract(moved_shape, c("position_matrix", "x")))

Plane wave/plane interface transmission coefficient

Description

Plane wave/plane interface transmission coefficient

Usage

transmission_coefficient(interface1, interface2, mode = "DWBA")

Arguments

interface1

Dataframe object containing density (kg/m^3) and sound speed (m/s) values for a boundary/interface (1)

interface2

Dataframe object containing density (kg/m^3) and sound speed (m/s) values for a boundary/interface (2)

mode

Two options: coefficient calculation for "DWBA" and "KRM"

Value

Pressure-amplitude transmission coefficient at normal incidence.

Examples

seawater <- data.frame(density = 1026, sound_speed = 1480)
animal <- data.frame(density = 1050, sound_speed = 1530)
transmission_coefficient(seawater, animal)

Remove a user-defined target-strength model registration

Description

Remove a user-defined target-strength model registration

Usage

unregister_model(name, remove_persisted = TRUE)

Arguments

name

Canonical model name or alias.

remove_persisted

Logical scalar. When TRUE, any persisted registry entry is also removed from the user's config file.

Value

Invisibly returns the removed canonical model name.

Examples

if (interactive()) {
  initialize_demo <- function(object, frequency, ...) object
  solve_demo <- function(object) object
  register_model(
    "demo",
    initialize = initialize_demo,
    solver = solve_demo
  )
  unregister_model("demo")
}

Calculates the Euclidean norm across each row of a given matrix.

Description

Calculates the Euclidean norm across each row of a given matrix.

Usage

vecnorm( x )

Arguments

x

A matrix with numeric, real values.

Value

Calculates the Euclidean norm of a vector.

Examples

values <- matrix(c(1, 2, 3), ncol = 3)
vecnorm(values) # should yield 3.741657

Calculate the acoustic wavenumber (`k`) for a given frequency and sound speed.

Description

Calculates the acoustic wavenumber (k) for a given frequency and sound speed in water. The wavenumber is defined as:

k = \frac{2\pi f}{c}

where f is the frequency (Hz) and c is the sound speed (ms^{-1}). The wavenumber describes the spatial frequency of a sound wave and is fundamental in acoustic calculations.

Usage

wavenumber(frequency, sound_speed)

Arguments

frequency

Frequency (f, Hz)

sound_speed

Sound speed (c, m~s^{-1})

Value

Calculates the acoustic wavenumber (k) based on the sound speed of water.

Examples

wavenumber(frequency = 38e3, sound_speed = 1500)

Cylindrical Bessel function of the second kind, `Y_\nu(x)`, and its respective derivatives

Description

Computes the cylindrical Bessel function of the second kind (Y_\nu(z)), also known as the Neumann function or Weber function, and its derivatives through ycdk().

Usage

yc(l, n)

ycdk(l, n, k)

Arguments

l

Numeric. The order (\nu) of the Bessel function. Must be purely real; complex orders are not supported.

n

k

Non-negative integer. The order of the derivative for ycdk.

Details

The cylindrical Bessel function of the second kind satisfies the same differential equation as J_\nu(z):

z^2 \frac{d^2 Y_\nu}{dz^2} + z \frac{dY_\nu}{dz} + (z^2 - \nu^2) Y_\nu = 0

but represents the linearly independent second solution.

Supported argument types:

Purely real arguments (z = x, where x \in \mathbb{R}): Fully supported for both positive and negative values.
Purely imaginary arguments (z = iy, where y \in \mathbb{R}): Computed using the identity Y_\nu(iy) = i e^{-i\pi\nu/2} I_\nu(y) - \frac{2}{\pi} e^{i\pi\nu/2} K_\nu(y) where I_\nu and K_\nu are modified Bessel functions.
General complex arguments (z = x + iy, where x \neq 0 and y \neq 0): Not supported.

Special cases:

Y_\nu(0) = -\infty (singularity at the origin).
For negative real arguments: Y_\nu(-x) = \cos(\pi\nu) Y_\nu(x) + \sin(\pi\nu) J_\nu(x).
For integer order n: Y_n(-x) = (-1)^n Y_n(x).
k-th derivative (DLMF 10.6.1):

\frac{d^k}{dz^k} Y_\nu(z) = \frac{1}{2^k} \sum_{j=0}^{k} (-1)^j \binom{k}{j} Y_{\nu - k + 2j}(z)

Derivative:

Y'_\nu(z) = Y_{\nu-1}(z) - \frac{\nu}{z} Y_\nu(z)

Value

A complex vector containing:

yc: Y_\nu(z)
ycdk(..., k = 1): Y'_\nu(z) (first derivative)
ycdk(..., k = 2): Y''_\nu(z) (second derivative)
ycdk: Y_\nu^{(k)}(z) (k-th derivative)

References

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

Bessel's equation: https://dlmf.nist.gov/10.2
Negative argument identity (Y_\nu(-z)): Eq. 10.4.1 at https://dlmf.nist.gov/10.4
Imaginary argument identity (Y_\nu(iz)): Eq. 10.27.8 at https://dlmf.nist.gov/10.27

Examples

# Real argument, integer order
yc(0, 1)
yc(1, 2.5)

# Real argument, fractional order
yc(0.5, 3)

# Negative real argument
yc(2, -1.5)

# Purely imaginary argument
yc(1, 1i)
yc(2, 3i)

# Singularity at origin
yc(0, 0) # Returns -Inf

# First derivative
ycdk(1, 2, 1)

Calculate Young's modulus (E).

Description

Calculates Young's modulus (E) from two of the three other elastic moduli: bulk modulus (K), shear modulus (G), or Poisson's ratio (\nu). Assumes 3D material properties.

The relationships used are:

E = \frac{9KG}{3K + G}

E = 3K(1 - 2\nu)

E = 2G(1 + \nu)

Usage

young(K = NULL, G = NULL, nu = NULL)

Arguments

K

Bulk modulus (Pa).

G

Shear modulus (Pa).

nu

Poisson's ratio (Dimensionless).

Value

Young's modulus (E, Pa).

Examples

young(K = 2.5e9, G = 1.1e9)

Spherical Bessel function of the second kind, `y_\nu(z)`, and its respective derivatives

Description

Computes the spherical Bessel function of the second kind (y_\nu(z)), also known as the spherical Neumann function, and its k-th derivatives.

Usage

ys(l, n)

ysdk(l, n, k)

Arguments

l

Numeric. The order of the spherical Bessel function. Can be integer or fractional.

n

Numeric or matrix. The argument (z) at which to evaluate the function. If a matrix is provided, the function is applied column-wise.

k

Non-negative integer. The order of the derivative for ysdk.

Details

The spherical Bessel function of the second kind is related to the cylindrical Bessel function by:

y_\nu(z) = \sqrt{\frac{\pi}{2z}} Y_{\nu+1/2}(z)

where Y_\nu(z) is the cylindrical Bessel function of the second kind.

The spherical Bessel functions satisfy the same differential equation as j_\nu(z):

z^2 \frac{d^2 y_\nu}{dz^2} + 2z \frac{dy_\nu}{dz} + [z^2 - \nu(\nu+1)] y_\nu = 0

Special cases:

y_\nu(0) = -\infty (singularity at the origin).
y_0(z) = -\frac{\cos(z)}{z}
y_1(z) = -\frac{\cos(z)}{z^2} - \frac{\sin(z)}{z}

Derivatives:

First derivative: y'_\nu(z) = \frac{\nu}{z} y_\nu(z) - y_{\nu+1}(z)
Second derivative: y''_\nu(z) = -\frac{\nu}{z^2} y_\nu(z) + \frac{\nu}{z} y'_\nu(z) - y'_{\nu+1}(z)

Value

A numeric vector or matrix (matching the input structure) containing:

ys: y_\nu(z)
ysd: y^{(k)'}_l(z) (k-th derivative)

References

NIST Digital Library of Mathematical Functions. https://dlmf.nist.gov/

Spherical Bessel functions: https://dlmf.nist.gov/10.47
Relation to cylindrical Bessel functions: Eq. 10.47.4 at https://dlmf.nist.gov/10.47

Examples

# Spherical Bessel function of the second kind
ys(0, 1)
ys(1, 2.5)

# Fractional order
ys(0.5, 3)

# Vector input
ys(0, c(1, 2, 3))

# Singularity at origin
ys(0, 0) # Returns -Inf

# First derivative
ysdk(1, 2, 1)

# Second derivative
ysdk(1, 2, 2)

# 3rd derivative
ysdk(1, 1, 3)

# 4th derivative
ysdk(1, 1, 4)

Package {acousticTS}

Arbitrary body shape

Description

Value

See Also

Examples

Backboned fish (BBF) object/class.

Description

Value

See Also

Examples

Body-backbone composite model (BBFM)

Description

Value

Usage

Arguments

Theory

References

Examples

Bent cylinder modal series (BCMS) solution

Description

Value

Usage

Arguments

References

Examples

Solid and calibration sphere (CAL) object/class.

Description

Value

See Also

Examples

Composite scatterer (CSC) object/class.

Description

Value

See Also

Examples

Cylindrical body shape

Description

Value

See Also

Examples

Distorted wave Born approximation (DWBA) for weak scatterers

Description

Value

Usage

Arguments

Theory

Implementation

References

See Also

Examples

Elastic cylinder modal series (ECMS) solution

Description

Value

Usage

Arguments

References

Examples

Elastic-based scatterer (ELA) object/class.

Description

Value

See Also

Examples

Elastic shelled scatterer (ESS) object/class.

Description

Value

See Also

Examples

Elastic-shelled sphere modal series (ESSMS) solution

Description

Value

Usage

Arguments

Theory

Implementation

References

See Also

Examples

Finite cylinder modal series (FCMS) solution

Description

Legendre Polynomial of the First Kind, `P_\nu(x)`