API Reference

AbstractBody

Supertype of scattering geometries. Construct a Sphere, Spheroid, Cylinder or Shell, then pass it to a solver with a boundary condition and exterior wavenumber. Geometry dimensions are in meters.

Sphere(radius)

A sphere of positive radius [m]. Monostatic scattering is independent of orientation. Sphere modal and kirchhoff calls do not take incidence_angle. Numerical BEM/MFS solvers accept it to set the incident direction for directional field queries.

Spheroid(a, b)

Spheroid of revolution with semi-axis a [m] along the x axis of symmetry and equatorial semi-axis b [m]. Prolate if a > b, oblate if a < b.

Cylinder(radius, length; radius_curvature=Inf, endcap_depth=0.0)

A finite circular cylinder of the given radius and length [m].

• radius_curvature [m]: Inf (default) is straight. A finite value bends the cylinder in the xy plane, with midpoint at the origin and midpoint tangent along +x. modal applies a near-broadside correction. kirchhoff and mfs(body, ...) describe the lateral surface only. Use bem(...; method=:full) or mfs(mesh(...; method=:full), ...) for closed surfaces.
• endcap_depth [m]: 0.0 (default) uses flat end caps. A positive value caps the cylinder with half-spheroid domes of that depth instead. Full BEM and straight-cylinder MFS honor this field. Axisymmetric BEM and FEM always use flat ends.

Full meshing requires radius_curvature > radius, an arc shorter than a full circle, and nonintersecting ends. See Closed bent cylinders for the bent-geometry conventions.

Shell(body, thickness)

A structural shell of positive thickness [m] inside the outer surface of a Sphere or Spheroid. For a prolate spheroid, thickness is measured at the equator and the inner surface is confocal. Solve with fem and a structural Shelled material. The thickness must be smaller than the body's radius.

Irregular(r, order; npoints=8*order+16)
Irregular(a, rc, rs)

A body of revolution about the z axis, for smooth irregular shapes between the canonical (Sphere, Spheroid) and general numerical (bem/mfs) bodies. Solve with fourier.

The first form Fourier-fits a harmonic order series to a meridian profile function r(theta) in m, the radial distance from the origin at polar angle theta, sampled on theta in [0,pi] with npoints quadrature nodes. The profile is extended evenly about the axis, so the fit is a cosine series and both poles lie on the axis.

The second form supplies the Fourier series R(theta) = a + sum_n rc[n]*cos(n*theta) (Eq. (21)) directly. a is the mean radius and rc[n] the deviation coefficients for harmonic order n = 1:length(rc). Sine coefficients rs must be zero, since any sine term moves the poles off the axis of symmetry.

RevolvedBody(x, radius; closed=false)
RevolvedBody(profile; n=64, closed=false)

Revolve a simple piecewise-linear meridian about the Cartesian x axis. Coordinates are in meters. For closed=false, the first and last radii must be zero and every interior radius positive. For closed=true, the profile is a closed loop strictly away from the axis, as for a toroid. The final vertex may repeat the first. Either traversal direction is accepted and converted to outward orientation. Crossing, touching and degenerate profiles are rejected.

The function form samples profile(t) -> (x, radius) on 0 <= t <= 1 using n segments. Increase n to converge the sampled geometry. Subsequent meshing subdivides these segments without smoothing or changing the supplied profile. Use bem for axisymmetric or full-3D scattering, or pass a full mesh to mfs or kirchhoff.

LoftedBody(centers, semiaxes; directions=nothing, twists=nothing)

Closed ruled loft through elliptical sections. centers is a 3 by N matrix in meters and semiaxes a 2 by N matrix of positive lengths in meters. Ends are closed with planar elliptical caps. Adjacent sections are connected without internal caps. Full surface BEM, MFS and Kirchhoff are available.

Optional directions is a 3 by N matrix of section normals pointing along the chain. Otherwise normals follow the centerline, bisecting interior bends. The first section's first axis is projected from +y (or +z if parallel to the normal). Subsequent frames use parallel transport. twists supplies N rotations in radians about the section normals. Section order and frames determine the loft. Intersecting or folded surfaces are rejected during meshing.

Ellipsoid(a, b, c)
Ellipsoid(semiaxes)

Triaxial ellipsoid centered at the origin, with positive Cartesian x, y, z semi-axes in meters. Use full surface bem, mfs or kirchhoff. For specialized axisymmetric solvers use Spheroid.

Superellipsoid(a, b, c; axial_exponent=1, equatorial_exponent=1)

Superellipsoid centered at the origin with semi-axes in meters. For polar angle theta from +x and azimuth phi from +y toward +z, its surface is x=a*spow(cos(theta),e1), y=b*sin(theta)^e1*spow(cos(phi),e2), z=c*sin(theta)^e1*spow(sin(phi),e2), where spow(u,e)=sign(u)*abs(u)^e, e1=axial_exponent and e2=equatorial_exponent. Both exponents are positive. Unit exponents give an ellipsoid. Small exponents produce boxlike shapes and exponents above two can produce concave shapes with cusps.

Use full surface BEM, MFS or Kirchhoff. Geometry and quadrature must be refined independently. Strong curvature or cusps can require linear elements and a finer mesh to pass surface validation. No elastic-solid or volume-FEM dispatch is implied.

Torus(major_radius, minor_radius)
Torus(major_radius, (axial_radius, radial_radius))

Ring torus about the x axis, centered at the origin, with circular or elliptical tube cross-section. All lengths are in meters. major_radius > radial_radius is required, excluding singular horn tori and self-intersecting spindle tori. Supports axisymmetric/full BEM and full surface MFS/Kirchhoff. Axisymmetric BEM meshes the closed meridian loop. Full meshing uses the smooth toroidal surface.

Cone(radius, length)

Closed circular cone, with base at x=-length/2 and tip at x=length/2. Lengths are in meters. Returns a RevolvedBody.

Bicone(radius, length; waist=0.5)

Two circular cones joined base-to-base with tips at x=+/-length/2. The common base has radius in meters and lies a fraction waist along the total length from the negative tip. Requires 0 < waist < 1. Returns a RevolvedBody.

Frustum(radius_left, radius_right, length)
Frustum((b_left, c_left), (b_right, c_right), length)

Closed circular or elliptical frustum along x, centered at the origin. Lengths are in meters. Circular end radii may be zero at one end, giving a cone. Elliptical semi-axes must be positive. Returns a RevolvedBody or LoftedBody, respectively.

FrustumChain(x, radii)
FrustumChain(x, semiaxes::AbstractMatrix)

Closed chain of circular or elliptical frustums with strictly increasing axial stations x in meters. radii is a vector, or semiaxes has two rows for the y and z semi-axes. Circular radii may vanish only at endpoints. Caps are added only at the two ends. For displaced or tilted sections use LoftedBody.

IncidentField

Supertype of incident excitations for solvers that accept an incident keyword. See PlaneWave, SphericalWave and BesselBeam. Full-3D BEM, closed-surface MFS and volume FEM evaluate incident_pressure and incident_gradient. Sphere modal uses incident_coefficient for the three built-in axisymmetric fields. Acoustic spheroid modal and single elastic spheroid/shell T-matrix paths project pointwise Cauchy data. Other solver bases do not yet project general incident fields. Explicit directions use Cartesian solver coordinates; numerical observation defaults still follow the solve's incidence-angle keywords.

PlaneWave(; direction=nothing, amplitude=1, phase=0)

A plane wave amplitude * exp(i*phase) * exp(i*k*dot(direction,x)) under exp(-i*omega*t). A supplied Cartesian direction is normalized. direction=nothing uses the solver's incidence angles, or +x for sphere modal and standalone field queries. phase is in radians at the origin. PlaneWave() preserves the default unit wave.

SphericalWave(range; direction=(1,0,0), amplitude=1, phase=0)

An outgoing point-source wave amplitude * exp(i*phase) * exp(i*k*R)/R, where R = norm(x + range*direction). The source lies at -range*direction in meters; the normalized direction is its propagation axis at the origin. The amplitude has pressure-times-length units if pressure is dimensional; it is not normalized to unit pressure at the origin. Sphere modal requires range > radius. Phase is in radians, and there is no 1/(4pi) factor.

BesselBeam(angle; direction=(1,0,0), amplitude=1, phase=0)

A non-diffracting zeroth-order Bessel beam along the normalized Cartesian direction, with half-conical angle angle [rad] between its plane-wave components and that axis (Gong et al., LIP2016 proceedings; Sapozhnikov and Bailey, 2013, Sec. III.B). angle = 0 is a plane wave. Its pressure is amplitude * exp(i*phase) * J0(k*sin(angle)*rho) * exp(i*k*cos(angle)*s), where s=dot(direction,x) and rho=norm(x-s*direction). Phase is in radians at the origin.

incident_pressure(field::IncidentField, k, point)

Evaluate the complex incident pressure at one Cartesian point [m], with exterior wavenumber k [rad/m], under exp(-i*omega*t). Built-in fields can be reused at different frequencies. Callable IncidentField(p, grad) fields are already tied to their construction frequency; k cannot retune those callbacks. Implement this and incident_gradient for custom pointwise fields.

incident_gradient(field::IncidentField, k, point)

Cartesian gradient of incident_pressure, in pressure units per meter. Returns three complex components, with no complex conjugation. Custom fields must provide a source-free Helmholtz pressure and its matching gradient near the target; callbacks must be safe for concurrent assembly and sampling.

incident_coefficient(field::IncidentField, degree, k)

Regular spherical coefficient Q_degree/(2degree+1) about the origin and the built-in field's own axis: p = sum((2l+1)*c_l*j_l(k*r)*P_l(cos(theta))). Includes complex amplitude and phase. For a spherical source the expansion converges only for r < range. Available for PlaneWave, SphericalWave and zeroth-order BesselBeam; arbitrary callbacks are not automatically projected.

Rigid()

Rigid boundary with zero total normal velocity, for supported geometries and solvers.

PressureRelease()

Soft boundary with zero total acoustic pressure, for supported geometries and solvers.

Impedance(zeta)

Locally reacting boundary with specific acoustic impedance ratio zeta = Z/(ρc), dimensionless and relative to the exterior fluid, under the exp(-iωt) convention ∂p/∂n = -ik p/zeta at the surface. zeta must have a nonnegative real part (a passive, non-generating boundary) and be nonzero. Rigid and PressureRelease are its zeta → ∞ and zeta → 0 limits. Supported by modal(Sphere, ...) and by bem(...; method = :axisymmetric) on Sphere/Spheroid/straight Cylinder, at any incidence angle, including incidence_angle_sweep's factorized reuse. The direct BEM solve becomes ill-conditioned as zeta → 0. Use PressureRelease there.

FluidFilled(density_contrast, soundspeed_contrast; coupling=:full)

Homogeneous fluid transmission boundary condition (Anderson, 1950). Gas-filled bodies use the same boundary condition with different material contrasts.

• density_contrast is ρinterior/ρexterior.
• soundspeed_contrast is cinterior/cexterior.
• coupling affects the spheroid modal series only (the sphere is diagonal by symmetry). :full solves the complete off-diagonal boundary coupling. :diagonal uses a cheaper approximation that degrades at higher ka and larger eccentricity.

See Modal series.

SpatialFluid(density_contrast, soundspeed_contrast; min_soundspeed_contrast)

Lossless spatially varying fluid for fem(...; method=:volume). Each contrast is a positive real constant or a callable x -> value, relative to the homogeneous exterior fluid. x contains Cartesian coordinates in meters in the volume FEM solution frame, the same frame as region centers and pressure queries, with the default symmetry axis along +z. Profiles do not move or rotate automatically with a region.

The positive lower bound min_soundspeed_contrast sets the shortest wavelength used for meshing. Sampled speeds below this bound are rejected. Callbacks must be deterministic and safe to evaluate concurrently. Resolve variation of the profiles with h/h_body; represent discontinuities by separate regions.

Supports a single Sphere/Spheroid or the coupled-region volume FEM interface. The exterior and its radiation closure remain homogeneous. This material is not supported by free_surface, which requires a reflected material profile.

Alias for FluidFilled, provided for gas-filled spheres, which solve the same boundary-value problem.

SolidElastic(density_contrast, speed_longitudinal_contrast, speed_transversal_contrast)

Solid elastic sphere boundary condition (MacLennan 1981), the classical sonar calibration-sphere model (e.g. tungsten carbide, steel reference spheres). Material properties are contrasts relative to the exterior medium, matching ElasticLayer's convention:

• density_contrast = ρbody / ρext
• speed_longitudinal_contrast = cL / cext, speed_transversal_contrast = cT / cext.

Uses Hickling's (1962) resonance form (sin η, cos η) rather than a boundary-matrix determinant like ElasticLayer/Shelled: there's no interior fluid, so it's a direct ratio of tangent terms. For the package's exp(-iωt) time convention and outgoing first-kind Hankel waves, the amplitude is -i/k * Σ (2m+1) Pₘ(cosθ) Aₘ with Aₘ = sin η (-i cos η - sin η), which maps exactly onto this package's existing form_function/target_strength convention, with target_strength(f) = 20 log10(|f|).

ViscoelasticSolid(density_contrast, speed_longitudinal_contrast, speed_transversal_contrast;
    loss_longitudinal=0.0, loss_transversal=0.0)

Solid with hysteretic damping, for example bone, with the contrasts of SolidElastic. loss_longitudinal and loss_transversal are the loss factors tan δ of the longitudinal and shear moduli, which become M(1 - i loss_longitudinal) and μ(1 - i loss_transversal) for the package's exp(-iωt) convention. Supported as a region material of the volume fem(bodies, materials, k).

Shelled(material, interior, radius_ratio)
Shelled(poisson, density, youngs_modulus)

The single boundary condition/material type for every shell in this package.

The three-argument form pairs a material layer (FluidLayer, ElasticLayer, or a LayeredMaterial) with either a VacuumInterior or a FluidInterior, for use as a boundary condition with modal/kirchhoff/fem(::Sphere/Cylinder, ...). Examples:

• Shelled(FluidLayer(...), VacuumInterior(), radius_ratio)
• Shelled(FluidLayer(...), FluidInterior(...), radius_ratio)
• Shelled(ElasticLayer(...), FluidInterior(...), radius_ratio)
• Shelled(LayeredMaterial(ViscousLayer(...), ElasticLayer(...), radius_ratio_wall), FluidInterior(...), radius_ratio_core)

radius_ratio is the inner/outer shell surface radius, in (0,1). a in every target_strength/form_function call is the shell's outer radius. When material is a LayeredMaterial, the innermost material interface must be strictly outside the enclosing Shelled's interior radius. Spherical modal supports arbitrary finite compositions of FluidLayer and ElasticLayer with a fluid or vacuum core. Mixed stacks require ElasticLayer(interior_coupling = :generalized). For a fluid core, FEM also accepts viscous layers in spherical and confocal spheroidal stacks. method=:volume solves the complete coupled field, while spherical method=:radial supports only the monopole for these stacks.

The one-argument-triple form Shelled(poisson, density, youngs_modulus) instead builds an ElasticFEMLayer with no interior/radius_ratio, for use with fem(::Shell, ::Shelled, ...).

FluidLayer(density_contrast, soundspeed_contrast)

A fluid spherical shell layer (no shear waves), e.g. a swim bladder wall modeled as fluid rather than solid tissue (Jech et al., 2015). density_contrast is ρshell/ρexterior and soundspeed_contrast is cshell/cexterior, both relative to the exterior medium. Pair with VacuumInterior for a pressure-release interior or FluidInterior for a fluid interior, via Shelled.

See Modal series for the boundary-matching derivation.

ElasticLayer(density_contrast, speed_longitudinal_contrast, speed_transversal_contrast; interior_coupling=:generalized)

An isotropic elastic spherical shell layer (Goodman and Stern, 1962), paired with a FluidInterior via Shelled. All contrasts are relative to the exterior medium.

• density_contrast is ρshell/ρext.
• speed_longitudinal_contrast and speed_transversal_contrast are cL/cext and cT/cext, the shell's longitudinal and shear wave speeds.
• interior_coupling: :generalized (default) uses the interior fluid's own wavenumber and density. :identical_fluid uses the exterior fluid's properties at the inner radius instead (Stanton, 1990), agreeing with :generalized only when the interior and exterior fluids match.

See Modal series for the boundary-matching determinant.

ViscousLayer(soundspeed_exterior, density_contrast, soundspeed_contrast,
             kinematic_viscosity_compressional, kinematic_viscosity_shear)

A viscous fluid shell layer (Feuillade and Nero, 1998), e.g. the flesh surrounding a fish's swimbladder. FEM supports it alone in Shelled or within a LayeredMaterial. The spherical viscous/elastic modal model uses it as the outer layer.

• soundspeed_exterior is the exterior medium's sound speed in m/s.
• density_contrast and soundspeed_contrast are lossless reference density/compressional-speed contrasts, ρ2/ρ1, c2/c1, relative to the exterior medium.
• kinematic_viscosity_compressional is (bulk + 4shear/3)/density and kinematic_viscosity_shear is shear/density, both in m²/s, for dynamic bulk and shear viscosities in Pa s and this layer's density in kg/m³. Set both to 0.0 for the inviscid fluid limit, which has no shear stiffness.

Use spherical modal for the supported viscous/elastic monopole model, or fem for layered spheres and confocal spheroids with a fluid interior. The viscous material is distinct from a hysteretically damped ViscoelasticSolid.

LayeredMaterial(outer, inner, radius_ratio)

Two concentric shell material layers. radius_ratio is the inner layer's outer radius divided by the outer layer's outer radius, in (0,1). For spherical modal scattering, FluidLayer and ElasticLayer entries can be nested to any finite depth; each material's density and wave-speed contrasts are relative to the exterior fluid. Fluid layers use pressure and normal-velocity continuity, while elastic layers retain longitudinal and shear motion with traction and displacement conditions. Nesting a LayeredMaterial in inner makes its radius ratio local to the enclosing layer's outer radius. For example, LayeredMaterial(f1, LayeredMaterial(f2, f3, 0.75), 0.8) has interfaces at 0.8 and 0.6 times the body's outer radius. The viscous-flesh-over-elastic-wall monopole model (Feuillade and Nero, 1998) remains supported:

Shelled(LayeredMaterial(ViscousLayer(...), ElasticLayer(...), radius_ratio_wall),
    FluidInterior(...), radius_ratio_core)

VacuumInterior()

A void/vacuum shell interior: pressure-release (p=0) at the shell's own inner surface, no interior medium. Pairs with FluidLayer to reproduce the former ShellSoft boundary condition, see Shelled.

FluidInterior(density_contrast, soundspeed_contrast)

A fluid- or gas-filled shell interior. density_contrast = ρinterior/ρexterior, soundspeed_contrast = cinterior/cexterior, both relative to the exterior medium (not to the shell). Pairs with FluidLayer (former ShellFluidFilled) or ElasticLayer (former ElasticShell), see Shelled.

modal(body::AbstractBody, boundary::AbstractBoundaryCondition, k; incidence_angle=π/2, kwargs...)

Modal-series result, returns a ModalSolution. Dispatches on body's concrete type. Sphere backscatter is angle-independent, with no incidence_angle keyword, but accepts incident::IncidentField=PlaneWave() (see SphericalWave and BesselBeam); angle is then measured from the incident field's own axis. A bent Cylinder automatically applies the Fresnel bend-coherence correction (see Cylinder). Acoustic spheroids accept incident=field, including pointwise callbacks, by surface projection. incident_n_eta=max(32,2n_max+12) and incident_n_phi=max(32,4m_max+4) control incident quadrature independently of modal truncation. Observation angles remain body-frame scatter_angle/scatter_azimuth. Spheroid solutions with incident=field provide far-field amplitudes only. Post-process with target_strength(sol) in dB re 1 m² or scattering_amplitude(sol), the complex scattering amplitude in m.

tmatrix(body::Spheroid, boundary, k; incidence_angle=π/2, incidence_azimuth=0,
    scatter_angle=π-incidence_angle, scatter_azimuth=incidence_azimuth+π, m_max, n_max, check=true)

Transition-matrix scattering by a prolate or oblate spheroid, returns a TMatrixSolution. boundary is a SolidElastic solid or Shelled(ElasticLayer(...), FluidInterior(...) or VacuumInterior(), radius_ratio), an elastic shell whose confocal inner surface has an equatorial semi-axis radius_ratio times the outer one. A Shelled(LayeredMaterial(...), ...) containing both fluid and generalized elastic layers is also supported for prolate spheroids with aspect ratio at most 1.25 and ka ≤ 1.5 through the default projected method. For a fluid core, method=:farfield builds a volume-FEM-generated angular transition through aspect ratio 1.5 and ka ≤ 1.8. The returned TMatrixSolution retains this transition: reuse it with scattering_amplitude(solution; incidence_angle, angle, azimuth) or target_strength to evaluate other directions without rebuilding FEM. This path accepts polar_order=6, m_max=4, points_per_wavelength=6, h, h_body, domain_radius and dtn_order. The default polar/azimuthal grid requires three incidence solves on one assembly; check=true adds a broadside solve and rejects a held-out angular error above 1%. Increase polar_order and m_max together to check angular convergence; refine the volume/interface meshes and exterior closure separately. Angles are in radians from the axis of symmetry, and the defaults give backscatter. m_max and n_max truncate the azimuthal orders and degrees. Single elastic shells warn when the reduced-order amplitude changes by more than 1%; mixed layers reject a change above 3%. Pass check = false to skip that check. Post-process with target_strength or scattering_amplitude.

Single elastic spheroids/shells accept incident=field, projecting incident pressure and gradient into their regular spheroidal basis. incident_n_eta=max(32,2n_max+12) and incident_n_phi=max(32,4m_max+4) control incident quadrature separately. The transition is assembled once per azimuthal order for both incident Fourier sectors. This option is not available for mixed-layer or method=:farfield transitions.

See Transition-matrix solutions.

kirchhoff(body::AbstractBody, boundary::AbstractBoundaryCondition, k; incidence_angle=π/2)

High-frequency (physical-optics) result, returns a KirchhoffSolution. Same body-type dispatch and bend-auto-detection as modal. Post-process with target_strength(sol) or scattering_amplitude(sol).

kirchhoff(surface::Mesh, boundary, k; incidence_angle=π/2, incidence_azimuth=0)

Kirchhoff physical-optics backscatter on a supplied full-3D surface, using its quadrature nodes, outward normals and endcaps. For incident propagation d, integrate only source-facing points with dot(n,d) < 0:

f = im*k*Rc/(2pi) * integral(dot(n,d)*exp(2im*k*dot(d,y)), surface).

Here Rc is the normal-incidence pressure reflection coefficient. The time convention is exp(-im*omega*t), with outgoing scattered pressure f*exp(im*k*r)/r. Matching canonical meshes reproduce the analytic-shape Kirchhoff amplitudes to quadrature/geometry accuracy. Local normal selection does not test visibility: a concave surface may include self-shadowed points. Returns a KirchhoffSolution.

kirchhoff(body::Union{RevolvedBody,Torus,LoftedBody,Ellipsoid,Superellipsoid}, boundary, k;
    meshsize, qorder=4, mesh_order=2, kwargs...)

Generate a full surface and evaluate Kirchhoff backscatter. The same local-normal illumination rule as kirchhoff(surface, ...) applies, without self-shadowing tests.

fem(body::AbstractBody, boundary::AbstractBoundaryCondition, k; method=:radial, R=1.2*characteristic_radius, incidence_angle=π/2, adaptive=false, kwargs...)

Finite-element result, returns a FEMSolution. Post-process with target_strength(sol) in dB re 1 m².

method:

• :radial: radial FEM with an exact Dirichlet-to-Neumann closure. Sphere only, angle independent. Covers Rigid, PressureRelease, FluidFilled, SolidElastic, and elastic or fluid Shelled boundaries on a Sphere, plus SolidElastic/elastic Shelled on a Cylinder. adaptive=true refines n_elements until target_tol is met (Rigid/PressureRelease/ FluidFilled only).

• :meridian: 2D (ρ,z) meridian FEM with the angular part discretized. Sphere supports Rigid and PressureRelease with axial incidence. Cylinder/Spheroid also support FluidFilled and general incidence_angle. For Spheroid, mode_threads=1 limits concurrent mode factorizations by default. Its default m_max follows the equatorial radius with a fluid-interior guard, and is zero at axial incidence. Explicit m_max overrides this estimate. Set retain_fields=false for far-field-only sweeps to omit stored nodal pressure. This preserves far-field output but disables scattered/total pressure queries. Spheroids additionally accept order=2:8 for higher-order mapped elements with element-interior elimination. The default order=1 retains the bilinear mesh. Higher-order defaults size n_r and n_theta from the wavelength, including a fluid interior. Explicit mesh counts are element counts. adaptive=true refines individual Fourier modes until their combined mesh-change estimate is below target_tol dB in backscatter TS (default 0.01), with at most max_refinements=4 increases per mode. Inspect diagnostics(sol).refinement.converged. This estimates spatial convergence, independently of m_max and l_max, and does not bound phase or bistatic error.

• :volume: full-3D finite elements on curved order-2 tetrahedra. Covers Sphere and Spheroid with Rigid, PressureRelease, FluidFilled, SolidElastic and elastic Shelled boundaries, with a fluid or empty interior. The default closure = :auto uses the exact Dirichlet-to-Neumann map on a sphere or a perfectly matched layer, whichever gives the smaller domain, and :dtn, :pml, :pml_spherical and :pml_spheroidal force a closure. Accepts incidence_angle, incidence_azimuth, points_per_wavelength, domain_radius, clearance, pml_thickness, pml_sigma, and solver (:auto, :direct or :iterative), and supports angle/azimuth in scattering_amplitude.

R is the Dirichlet-to-Neumann truncation radius in m, default 1.2 times the body's characteristic radius. See fem(shell::Shell, ...) for the elastic-shell/fluid-coupling case.

Supported radial and meridian spheres also support scattering_amplitude(sol) in complex meters. See FEM and shell coupling for field normalization and per-boundary support.

fem(bodies::AbstractVector{<:Union{Sphere,Spheroid}}, materials::AbstractVector, k;
    method=:volume, parents=collect(0:length(bodies)-1), centers, orientations,
    incidence_angle=π/2, incidence_azimuth=0, kwargs...)

Full-3D volume FEM of coupled fluid and elastic regions, for example a fish body with a gas-filled swimbladder and a bony backbone. Region i is bodies[i] with the contrasts of materials[i] relative to the unbounded exterior. parents[i] is the region immediately outside it, with 0 for the exterior, and the default is a nested chain. centers[i] is the region's center and orientations[i] the direction of its symmetry axis, in the frame whose origin is the phase reference of the far field. Regions may be nested or disjoint but must not partially overlap. The keywords of the single-body method = :volume apply, except closure = :pml_spheroidal. SpatialFluid supplies positive density and sound-speed contrast profiles at quadrature points, in the same global coordinate frame as centers.

Returns a FEMSolution. Post-process with scattering_amplitude(sol; angle, azimuth) or target_strength(sol; angle, azimuth).

fem(body::Union{Sphere,Spheroid}, boundary::Shelled{<:Union{LayeredMaterial,ViscousLayer}}, k;
    method=:volume, kwargs...)

FEM for concentric spherical or confocal spheroidal FluidLayer, ElasticLayer and ViscousLayer materials around a FluidInterior. For spheres, method=:radial uses quadratic displacement elements with n_elements=256 per region, including the core, and supports only m_max=0. It retains complex monopole scattering. Point-field queries require method=:volume, which solves the full 3D coupled field and also supports spheroids. Nested layer ratios scale each enclosing radius or equatorial semi-axis. The core ratio refers to the outer body, and spheroidal interfaces share its focal distance. Contrasts refer to the exterior.

fem(shell::Shell, boundary::Shelled, ext_density, ext_soundspeed, int_density, int_soundspeed, k;
    method=:general, incidence_angle=π/2, kwargs...)

Elastic-shell/fluid coupling, returns a FEMSolution. Post-process with target_strength(sol; angle, azimuth). boundary is built via Shelled(poisson, density, youngs_modulus). ext_density/ext_soundspeed and int_density/int_soundspeed are the absolute density [kg/m³] and sound speed in m/s of the exterior and interior fluids, not contrasts.

method=:thin is an axisymmetric reduction, shell.body isa Spheroid only, axial incidence only (incidence_angle = 0.0). Pass int_density=0 for a vacuum-backed shell.

method=:general (default) is a full through-thickness 2D shell FEM, general incidence, shell.body isa Union{Sphere,Spheroid}, always fluid-filled. Use a small int_density/ int_soundspeed for a near-vacuum limit.

See FEM and shell coupling for the shell theory.

bem(body::Union{RevolvedBody,Torus,LoftedBody,Ellipsoid,Superellipsoid}, boundary, k;
    method, n, meshsize, qorder=4, mesh_order=2, kwargs...)

Scatter from a generated geometry with rigid, pressure-release or homogeneous fluid/gas material. Revolved bodies and tori default to method=:axisymmetric. Lofts, ellipsoids and superellipsoids use method=:full. Full solves accept the same formulations, compression and convergence controls as supplied meshes. Axisymmetric solves use n meridian panels and m_max azimuthal modes. meshsize is the full-surface target edge length in meters.

bem(surface::Mesh, boundary, k; incidence_angle=pi/2, m_max, kwargs...)

Reuse an axisymmetric mesh of a revolution body for rigid, pressure-release or fluid scattering. Its meridian panels are used unchanged.

bem(body::AbstractBody, boundary::AbstractBoundaryCondition, k; method=:axisymmetric, incidence_angle=π/2, kwargs...)

Boundary-element solve, returns a BEMSolution. method=:axisymmetric supports Sphere/Spheroid/straight Cylinder. method=:full supports a generated Sphere/Spheroid/Cylinder or a supplied Mesh, and is required for a bent Cylinder. Post-process with target_strength(sol; angle, azimuth) (axisymmetric) or target_strength(sol; direction) (full 3D).

Full BEM accepts meshsize in m, geometry mesh_order (1, 2 or 3, default 2), quadrature qorder (default 4), correction, compression and gmres_kwargs. Rigid/soft full BEM defaults to formulation=:burton_miller (:cbie selects the conventional equation). Fluid full BEM defaults to formulation=:muller (:cbie selects the pressure-only system with interior traces eliminated). equilibrate=true scales the matrix before factorization. condition_limit=512 bounds the optional SVD condition-number calculation. Single-interface fluid Müller also accepts compression=(method=:hmatrix, tol=1e-8) with density interpolation, using block-preconditioned GMRES. It scales from local blocks, skips SVD condition estimates and accepts gmres_kwargs; dense LU remains the default.

See BEM and MFS for the underlying formulations and diagnostics for convergence and residual checks.

bem(body::Sphere, boundary::Shelled{FluidLayer}, k; n=default, kwargs...)

Two-surface (outer + inner mesh) fluid-shell BEM, boundary's own radius_ratio field gives the inner surface's radius, body.radius * boundary.radius_ratio. This two-surface formulation supports axial incidence only.

bem(surface::Mesh, boundary, k; incidence_angle=π/2, incidence_azimuth=0, kwargs...)

Solve scattering on a supplied full-3D surface with rigid, pressure-release or homogeneous fluid/gas material. The stored quadrature and outward normals are used directly. Wavenumber k is in inverse meters, including when the mesh input used centimeters or millimeters. Solver options are the same as bem(body, boundary, k; method=:full); mesh resolution and quadrature are selected when constructing surface. Returns a BEMSolution.

bem(surfaces::AbstractVector{<:Mesh}, materials::AbstractVector{<:FluidFilled}, k;
    parents=collect(0:length(surfaces)-1), incidence_angle=π/2,
    incidence_azimuth=0, equilibrate=true, condition_limit=512,
    correction=(method=:dim,), formulation=:muller, validation=(;),
    compression=(method=:none,), gmres_kwargs=(;))

Coupled fluid transmission across closed, disjoint full-3D interface meshes. Surface i encloses region i. parents[i] is the region immediately outside it, with 0 denoting the unbounded exterior. The default parents is a nested chain. materials[i] gives that region's density and sound-speed contrasts relative to the unbounded exterior. Only homogeneous, lossless scalar fluids are supported.

Meshes may have independent shapes, origins and orientations, but must not intersect or touch. validation=(maxdepth=20, maxwork=200000) controls the geometry checks.

Dense LU is the default. For Müller with density interpolation, compression=(method=:hmatrix, tol=1e-8) compresses self and cross-interface operators. Close-surface corrections and the low-frequency reconstruction guards are preserved. Right-preconditioned GMRES uses local cluster blocks and independent degree-two harmonic coarse spaces on each interface, coupled through the full operator. gmres_kwargs controls iteration tolerances, restart and iteration limit as in single-interface fluid BEM. The coupled default restart is 600; the other iterative defaults are unchanged. Equilibration uses local-block maxima; dense SVD condition estimates are skipped. Interior and exterior representation residuals are evaluated from the compressed blocks, without storing a second global dense matrix. They do not estimate compression error.

Returns a BEMSolution. Post-process with scattering_amplitude(sol; direction) or target_strength(sol; direction).

See Coupled fluid regions for the coupling equations, formulation and correction tradeoffs, and diagnostics fields.

Example

bem(surfaces, materials, k; parents = [0, 1, 1])

mfs(body::AbstractBody, boundary::AbstractBoundaryCondition, k; incidence_angle=π/2, offset=0.3*characteristic_radius, kwargs...)

Method-of-fundamental-solutions solve, returns an MFSSolution. Axisymmetric for Sphere/Spheroid/straight Cylinder. Lateral-only 3D point sources for a bent Cylinder (omits end caps). Use mfs(mesh(body; method=:full, ...), ...) for closed-surface conditions and general observation directions. offset is a maximum source displacement in m from the surface, reduced near flat-cap rims.

Axisymmetric MFS does not support a rigid straight cylinder with flat caps: the normal-offset source basis fails independent rim boundary checks. Use bem for that sharp-rim geometry, or a Cylinder with physically justified smooth caps.

For bent cylinders, n_s/n_phi (defaults 40/32, at least 3) set the axial and azimuthal source-grid counts. oversampling (integer, default 1) multiplies the collocation budget while keeping the source grid fixed. Values above 1 give a least-squares solve.

See BEM and MFS for source placement guidance and diagnostics for residuals, conditioning and rank (condition_limit=512 bounds the SVD size, 0 skips it).

mfs(body::Union{Sphere,Spheroid}, boundary::Shelled{FluidLayer,FluidInterior}, k;
    incidence_angle=0, n=40, oversampling=2, offset_outer=0.2b,
    offset_inner=0.12b, rtol=1e-6)

Axisymmetric two-interface fluid MFS with separate exterior, shell and core source sets. Shelled uses the usual outer-surface-relative fluid contrasts; the inner spheroid is confocal with equatorial semi-axis radius_ratio*b. Both offsets are in metres and must be positive. oversampling refines the collocation meshes while keeping the source meshes fixed. Held-out interface pressure and density-scaled normal-derivative RMS mismatches, normalized by unit incident pressure and by k respectively, are in diagnostics. The current implementation accepts axial incidence only.

mfs(body::Union{RevolvedBody,Torus,LoftedBody,Ellipsoid,Superellipsoid}, boundary, k;
    meshsize, qorder=4, mesh_order=2, kwargs...)

Generate a full surface and use point-source MFS. Supply offset for rigid/soft bodies or offset_ext/offset_int for fluids. All source-placement and independent boundary-residual controls of mfs(surface, ...) apply. Sharp rims, tips and concavities require particular care. Use BEM when normal-offset sources cannot represent the boundary accurately.

mfs(surface::Mesh, boundary::Union{Rigid,PressureRelease}, k;
    offset, source_mesh=surface, check_mesh=nothing,
    incidence_angle=π/2, incidence_azimuth=0, condition_limit=512)

Full three-dimensional point-source MFS on a closed surface. Place one source at each quadrature point of source_mesh, displaced inward by offset [m]. Enforce the boundary condition at surface's quadrature points with a dense least-squares solve. Both meshes must describe the same body. Use a coarser, low-quadrature-order source_mesh to keep the number of sources below the number of collocation points.

Source placement is suitable for smooth bodies when all sources remain strictly inside. Sharp edges and strongly concave surfaces can make normal offsets unreliable. Convergence requires separate source-spacing, offset and collocation checks. An optional check_mesh on the same body evaluates the boundary residual away from collocation points. diagnostics reports this residual, the fitted residual and optional matrix conditioning.

Incidence uses the full-BEM convention, (cos(β), sin(β)cos(α), sin(β)sin(α)). scattering_amplitude(solution; direction) evaluates the outgoing sources' far-field amplitude [m] directly; the default direction is monostatic backscatter for a plane wave.

mfs(surface::Mesh, boundary::FluidFilled, k;
    offset_ext, offset_int=offset_ext, source_mesh=surface, check_mesh=nothing,
    incidence_angle=π/2, incidence_azimuth=0, condition_limit=512)

Full-3D two-domain MFS on a closed surface. Exterior scattered sources are offset inward; interior transmitted sources are offset outward. Both source sets are checked against the curved surface before solving pressure and density-scaled normal-derivative continuity. Use separate, coarser source_mesh and independent check_mesh to control source spacing and held-out residuals. Curved, genuinely capped cylinders are supported when the source-side checks pass. diagnostics retains separate held-out pressure and velocity residuals when check_mesh is provided.

mfs(swimbladder::Mesh, backbone::Mesh, backbone_material::FluidFilled, k;
    bladder_offset, backbone_offset_ext, backbone_offset_int,
    bladder_source_mesh=swimbladder, backbone_source_mesh=backbone,
    check_bladder=nothing, check_backbone=nothing,
    incidence_angle=π/2, incidence_azimuth=0, condition_limit=512)

Coupled full-3D MFS for a pressure-release swimbladder and a disjoint penetrable backbone, following Pérez-Arjona et al. (2020), DOI 10.1093/icesjms/fsaa160. The package uses exp(-iωt) and outgoing exp(ikr)/r; the paper prints the opposite Green-function phase convention. Both arguments must be closed, outward-oriented full-3D meshes. backbone_material is a scalar fluid with density and sound-speed contrasts relative to water; it has no shear waves.

Place exterior sources inward from both surfaces and backbone-interior sources outward from the backbone. The three offsets are in meters and must keep each source set outside its represented domain. Coarser source meshes provide oversampling. Separate, finer check_bladder and check_backbone meshes measure held-out pressure/velocity boundary residuals for each condition. The result supports scattering_amplitude(sol; direction) and target_strength(sol; direction).

fourier(body::Irregular, boundary::AbstractBoundaryCondition, k;
       incidence_angle=π/2, continuation_steps=8, mapping_order=length(body.rc),
       m_max=_default_mode_count(k*body.a), n_max=m_max, rtol=1e-6, maxevals=1000)

Fourier-matching result, returns an FMSolution. Conformally maps body's meridian profile to a coordinate system where the mapped surface is exactly circular, then matches the boundary condition using spherical wave functions. See Fourier matching. Supports Rigid, PressureRelease and FluidFilled boundaries. mapping_order and continuation_steps control the conformal mapping (see solve_mapping). m_max/n_max truncate the modal series. rtol and maxevals set the tolerance and maximum node count of the boundary-matching quadrature. Post-process with target_strength(sol; angle, azimuth) or scattering_amplitude(sol; angle, azimuth), defaulting to backscatter.

Each solve is repeated at n_max and m_max reduced by 2. A warning is emitted when the far-field amplitude changes by more than 1e-2 of its peak, and the change is reported by diagnostics as convergence. See Fourier matching.

fourier(body::Sphere, boundary, k; kwargs...)
fourier(body::Spheroid, boundary, k; mapping_order=..., kwargs...)

Convenience overloads for the canonical bodies, matching bem/mfs's body-type coverage. Both convert body to an equivalent Irregular internally and solve with fourier. modal is exact and cheaper for these bodies. These overloads exist for interface consistency and cross-checking, not as the recommended solver. The returned FMSolution keeps the original Sphere/Spheroid in its body field.

A spheroid with aspect ratio above 2.5 defaults to a higher mapping_order and a matching m_max/n_max. See Fourier matching for the validated aspect-ratio range.

free_surface(body::Union{Sphere,Spheroid}, boundary, k, depth; condition=:pressure_release,
    incidence_angle=0, incidence_azimuth=0, orientation=[0,0,1], kwargs...)

Volume FEM scattering by body, centered on the normal of an infinite planar interface and submerged a depth [m] below it. condition = :pressure_release (default) is an air-water free surface, condition = :rigid an idealized seafloor. incidence_angle = 0 and incidence_azimuth give the direct wave's direction along the interface's outward normal, in the convention of fem(...; method = :volume). boundary is a region material (FluidFilled, SolidElastic, ViscoelasticSolid or ViscousLayer).

Solved exactly by the method of images: body and a mirror image across the interface form a coupled two-body volume FEM in an unbounded fluid, solved once for the direct wave and once for its specular reflection, and added with the interface's reflection coefficient (-1 for :pressure_release, +1 for :rigid). Accepts the keywords of fem(...; method = :volume) for coupled regions. Returns a FreeSurfaceSolution.

AbstractSolution

Supertype of results returned by modal, tmatrix, kirchhoff, fem, bem and mfs. Query target_strength, scattering_amplitude and diagnostics where available. Construct solutions through their solver rather than their internal storage fields.

Evaluate a field by calling solution(points; quantity=:pressure, kwargs...). The default delegates to pressure, including its field and region keywords and incident-pressure normalization. Point inputs have the same shapes as pressure.

Full-3D volume FEM also supports quantity=:displacement, :velocity, or :stress strictly inside elastic or ViscousLayer regions. These return complex Cartesian vectors [m or m/s] or 3-by-3 Cauchy stress tensors [Pa], respectively, in the solution frame, using exp(-iωt) and tension-positive stress. The local material determines the constitutive law. Scalar acoustic fluid and exterior regions do not support these mechanical queries.

Displacement and velocity require density_exterior [kg/m³] and soundspeed_exterior [m/s]. Mechanical queries accept pressure_amplitude=1 [Pa] per unit incident-pressure normalization. Stress needs no exterior scales; if a sound speed is supplied in a viscous region, it must match the solve. Velocity is -im*k*soundspeed_exterior times displacement. See Material fields in volume FEM for scaling and limits.

ModalSolution

Result of modal: the modal-series complex scattering amplitude f [m] at the angle(s) modal was called with. Post-process with target_strength or scattering_amplitude. Supported spheres also retain coefficients for pressure evaluation with PlaneWave, SphericalWave or BesselBeam, including their Cartesian direction and complex amplitude. Finite-cylinder and bent-cylinder paths include approximations.

TMatrixSolution

Result of tmatrix: the complex scattering amplitude f [m] of an elastic spheroid or shell at the incident and observation directions tmatrix was called with. Post-process with target_strength or scattering_amplitude. The method=:farfield path retains its angular transition internally and supports repeated direction queries through those same functions; diagnostics reports its construction checks.

KirchhoffSolution

Result of kirchhoff: the high-frequency (physical-optics) complex scattering amplitude f [m] at the angle(s) kirchhoff was called with. Post-process with target_strength or scattering_amplitude.

FEMSolution

Result of fem. Supported radial spheres retain complex backscatter coefficients and radial pressure or elastic potential fields. Post-process with scattering_amplitude or target_strength. For supported radial spheres, pressure samples acoustic pressure in the exterior, fluid shells and fluid interiors at Cartesian points. Structural Shell results retain surface traces and support observation angle/azimuth. Cylinder radial and meridian paths retain target strength only. Observation keywords are rejected outside the structural Shell case.

BEMSolution

Result of bem: axisymmetric (method=:axisymmetric, Sphere/Spheroid/straight Cylinder) or full 3D (method=:full) boundary-element surface data, including supplied closed surfaces and coupled fluid regions. Post-process with target_strength(sol; angle, azimuth) (axisymmetric) or target_strength(sol; direction) (full 3D).

MFSSolution

Result of mfs. Axisymmetric body solves use target_strength(sol; angle, azimuth). Full closed-surface solves use target_strength(sol; direction), defaulting to backscatter. The lateral-only bent-body overload returns a monostatic result, evaluated with target_strength(sol).

FMSolution

Result of fourier. Post-process with target_strength(sol; angle, azimuth) or scattering_amplitude(sol; angle, azimuth) (backscatter by default, same convention as axisymmetric bem/mfs). diagnostics reports the mapping's admissibility, the truncation orders and a truncation-consistency check. b_check holds the reduced-truncation coefficients.

FreeSurfaceSolution

Result of free_surface: the volume FEM solutions of a body driven by the direct incident wave and by its interface-reflected image, held separately with the interface's reflection sign. Post-process with target_strength, scattering_amplitude or pressure.

target_strength(boundary::AbstractBoundaryCondition, k, a; angle=π, m_max=default)

Target strength [dB re 1 m²] of a sphere under modal-series scattering (rigid, pressure-release, or fluid/gas-filled boundary conditions).

target_strength(boundary::AbstractBoundaryCondition, k, radius, length; aspect_angle=π/2, m_max=default)

Backscatter target strength [dB re 1 m²] of a finite circular cylinder. See form_function for the underlying complex amplitude.

target_strength(boundary, k, body::Spheroid; kwargs...)

Target strength [dB re 1 m²] of a prolate/oblate spheroid under a rigid, pressure-release, or fluid/gas-filled modal series. See form_function for keyword arguments.

target_strength(quad, xhat, k, p_scat, dpdn_scat)

Target strength [dB re 1 m²] of a full 3D BEM solution at observation direction xhat (see far_field).

target_strength(f)

Convert a scattering amplitude/length f [m] to target strength in dB re 1 m². Solver-specific target_strength(scatterer, ...) methods build f and dispatch here for the final conversion.

target_strength(solution::AbstractSolution; kwargs...)

Return target strength in dB re 1 m². Where complex amplitude is retained, this is 20 * log10(abs(scattering_amplitude(solution; kwargs...))), with the same observation keywords and backscatter defaults. Scalar-only FEM paths return their stored target strength. Observation support follows the underlying amplitude method; sphere radial/meridian and scalar-only FEM paths reject observation keywords.

target_strength(ps::Vector{Panel}, p_scat, dpdn_scat, k, theta)

Target strength [dB re 1 m²] of an axial-incidence axisymmetric BEM solution at scattering angle theta (see far_field).

target_strength(ps::Vector{Panel}, p_scat_modes, dpdn_scat_modes, k, theta, phi)

Target strength [dB re 1 m²] of an oblique-incidence axisymmetric BEM solution at scattering direction (theta, phi) (see far_field).

scattering_amplitude(solution; kwargs...)

Return the complex far-field scattering amplitude in meters. Axisymmetric BEM/MFS and structural shell FEM accept observation angle and azimuth [rad] in body coordinates; their defaults are backscatter, angle = pi - incidence_angle, azimuth = pi. Full BEM accepts a unit-vector direction, defaulting to the negative incident direction. When incident is supplied, numerical defaults use the solve's incidence-angle keywords, not the field's Cartesian axis; specify the observation explicitly. Cartesian body length is x, width is y and height/depth is z. Polar angles are from +x; azimuth is from +y toward +z, so (angle,azimuth)=(pi/2,0) points along +y. Bent MFS returns backscatter only. Modal/Kirchhoff observation is fixed at solve time and post-processing keywords throw ArgumentError. Supported radial spheres return complex backscatter amplitude without observation keywords. Sphere meridian and elastic cylinder radial FEM also return complex backscatter. Cylinder/spheroid meridian and volume FEM accept observation angle and azimuth. Any scalar-only FEM result rejects complex amplitude queries; use target_strength for those results.

TMatrixSolution from tmatrix(...; method=:farfield) accepts incidence_angle, incidence_azimuth, observation angle and azimuth without additional FEM solves. With no overrides, it uses the solve's directions. If either incidence keyword is supplied, omitted observation angles select backscatter at that incidence. Other T-matrix paths retain their solve-time directions and reject these keywords.

Examples

solution = modal(Sphere(0.01), Rigid(), 100.0)
amplitude = scattering_amplitude(solution)

pressure(solution, point; field=:total, region=nothing)
pressure(solution, points; field=:total, region=nothing)

Complex acoustic pressure under the exp(-iωt) convention. Plane-wave solutions use unit incident amplitude. Fields passed through incident keep their normalization. Coordinates are in meters.

point is a three-coordinate tuple or vector. A collection of points returns an array of the same shape. A real 3×N matrix stores points in columns and returns a vector of length N.

field selects:

• :total: incident plus scattered pressure outside the body, or total transmitted pressure inside a fluid interior or shell.
• :scattered: defined on and outside the body only.
• :incident: the retained unperturbed incident field (a plane wave by default).
• :interior: total pressure inside a homogeneous fluid body, a shell's fluid cavity, or a bounded coupled fluid region.
• :shell: total pressure in a fluid shell, including both surface traces.

region selects a specific fluid region for coupled fluid BEM (region=0 is the unbounded exterior, region=i the fluid inside interface i). Other solutions reject this keyword.

Not every solver/geometry/boundary combination supports every field/region option. See BEM and MFS and FEM and shell coupling for solver support and numerical caveats.

Example

solution = modal(Sphere(0.01), FluidFilled(1.2, 1.1), 100.0)
pressure(solution, (0.02, 0.0, 0.0); field=:scattered)
pressure(solution, [(0.0, 0.0, 0.0), (0.02, 0.0, 0.0)])

diagnostics(solution)

Return a named tuple of solver diagnostics for BEM, MFS, FEM, Fourier matching and the far-field-generated T-matrix. Modal, Kirchhoff and other T-matrix paths return nothing.

tmatrix(...; method=:farfield) reports angular orders, holdout_error, fem_solves, fem_assemblies, mesh sizes, domain radius, DtN order and system size.

Fourier matching reports admissible, m_max, n_max, convergence, convergence_tolerance and converged, which is nothing when n_max is too small to reduce.

Full-3D BEM reports converged, iterations, relative_residual, residual_history, unknown_count, meshsize, quadrature_order, and the solver settings used. Axisymmetric BEM/MFS/FEM report per-system entries in systems. MFS systems also report source counts, condition_number, numerical_rank and a held-out boundary_residual.

See BEM and MFS for field definitions and what each residual does and does not measure.

Example

solution = bem(Sphere(0.01), Rigid(), 100.0; method = :full, meshsize = 0.01)
diagnostics(solution).converged

Mesh

A discretized surface mesh, returned by mesh. The single public mesh type, whether the underlying representation is an axisymmetric meridian curve (method=:axisymmetric) or a full 3D triangulated surface (method=:full). body/method/resolution record what mesh(...) was called with. resolution is the maximum corner-edge length in meters. Inspect the surface with coordinates, normals, elements, and element_count.

mesh(body::Union{RevolvedBody,Torus,LoftedBody,Ellipsoid,Superellipsoid};
     resolution=nothing, k=nothing, method, qorder=4, mesh_order=2,
     validation=(;))

Mesh a generated geometry. RevolvedBody and Torus default to method=:axisymmetric, where resolution is the total number of meridian panels. Every supplied profile corner is retained. Other bodies require method=:full, where resolution is a target edge length in meters. Exactly one of resolution or positive exterior wavenumber k is required. Full surfaces are validated like supplied meshes. mesh_order is 1, 2 or 3.

mesh(body::AbstractBody; resolution=nothing, k=nothing, method=:axisymmetric,
     qorder=4, mesh_order=2)

Build a Mesh for body, the same construction bem/mfs use internally. Exactly one of resolution or k must be given. resolution sets panel count (:axisymmetric) or target element edge length in m (:full) directly. k in 1/m derives a wavenumber-appropriate default. For full surfaces, mesh_order (1, 2 or 3) controls triangle geometry and qorder controls quadrature. Supplied surfaces use mesh(path), mesh(generate) or mesh(nodes, triangles).

mesh(; semiaxes, resolution=0.5, center=(0,0,0),
    rotation=(axis=(0,0,1), angle=0), tip_ratio=1,
    mesh_order=3, qorder=5, validation=(;))

Construct a closed ellipsoid with semiaxes=(x,y,z) and center in meters. rotation gives a nonzero axis and a right-handed angle in radians, applied before translation. Mesh a unit sphere, then stretch, rotate and translate its nodes. resolution is the dimensionless target edge length on that sphere; physical edge lengths vary with stretching. tip_ratio in (0,1] reduces the target size at the local x poles, with size proportional to 1-(1-tip_ratio)*x^4 on the unit sphere. mesh_order (1, 2 or 3) and qorder control geometry and quadrature independently.

Examples

body = mesh(; semiaxes=(0.1, 0.018, 0.025), tip_ratio=0.4)
bladder = mesh(; semiaxes=(0.025, 0.006, 0.009), center=(0.01, 0.003, 0),
    rotation=(axis=(0,0,1), angle=deg2rad(10)), tip_ratio=0.4)

mesh(path::AbstractString; units=:m, qorder=4)
mesh(generate::Function; units=:m, qorder=4, provenance="generated Gmsh model")
mesh(nodes, triangles; units=:m, qorder=4, labels=nothing, provenance="supplied triangles")

Construct a full-3D Mesh from a Gmsh file, a function generate(gmsh) that builds and meshes a Gmsh model, or coordinate/connectivity matrices. Each column of nodes is a 3D point; each column of triangles contains 3, 6 or 10 one-based node indices in Gmsh's linear, quadratic or cubic triangle ordering. labels optionally gives one positive integer physical-group tag per triangle. Gmsh input preserves all surface physical tags and names.

Supply one connected, closed surface with outward-oriented triangles. Coordinates are converted from units (:m, :cm, :mm) to meters and retain their supplied Cartesian frame. No remeshing, hole filling, node merging or orientation repair is performed. Unsupported elements, open/nonmanifold surfaces, inconsistent normals, inward orientation and detected intersections raise ArgumentError. Curved elements use outward-rounded Bernstein bounds and adaptive subdivision. Acceptance requires positive Jacobians projected onto each element's corner plane, injective elements, and separation except at topologically shared edges/vertices. Strongly curved valid elements whose corner-plane projection folds are outside this acceptance criterion.

validation=(maxdepth=20, maxwork=200000) sets refinement and work limits. An unresolved case raises ArgumentError; neither exhausted limits nor small distances imply validity. Increasing the limits can resolve conservative bounds, but cannot repair invalid geometry.

The returned m.body records nodes in meters, connectivity in Gmsh ordering, per-element labels (tag/name pairs), units, input_units, orientation, provenance and validation. m.resolution is the maximum corner-edge length in meters. Pass m directly to bem. The Gmsh constructors require that no other Gmsh session is active.

components(solution; labels=nothing, solver_kwargs=(;))

Compare a coupled fluid-region BEM solution with each interface solved in isolation in the exterior medium. Preserve each surface's position, orientation, material contrast, incident direction and phase origin. The coupled solution is reused; isolated solves inherit its formulation, quadrature correction, equilibration, compression and iterative controls, with overrides in solver_kwargs.

Returns a comparison retaining coupled, isolated solutions and labels for the coupled response, isolated responses and their coherent sum. The coherent sum adds complex amplitudes, omitting mutual interactions. All contrasts refer to the original exterior medium, including for an interface originally enclosed by another region.

Pass this result to bistatic_sweep, or return it from the solver callback of frequency_sweep or incidence_angle_sweep. labels optionally supplies one name per interface; no further solves are needed for observation-angle sweeps.

frequency_sweep(solve, frequencies, sound_speed)

Call solve(k) once per frequency in Hz, with k=2π*frequency/sound_speed and exterior sound_speed in m/s. Retain target strength and complex amplitude when available. The callback may return a solution or a components comparison. Dense solution state is discarded after sampling. Plot the result directly with plot(sweep) or plot(sweep; quantity=:phase); multiple sweeps can share a comparison figure.

The result contains frequencies in Hz, exterior k in rad/m, target_strength in dB re 1 m², complex amplitudes in meters, and labels. Arrays have samples along the first dimension, with one column per label for component comparisons. amplitudes is nothing for scalar-only FEM results. When available, phase is angle.(sweep.amplitudes) in radians.

Examples

sweep = frequency_sweep(k -> modal(Sphere(0.01), Rigid(), k), 10e3:1e3:100e3, 1477.4)

frequency_sweep(surface::Mesh, material::FluidFilled, frequencies, sound_speed;
                training_frequencies, incidence_angle=π/2, incidence_azimuth=0,
                tolerance=1e-10, rank_tolerance=1e-12, capacity=16,
                maxbytes=64*1024^2, return_diagnostics=false)

Opt-in reduced-order frequency sweep for dense single-interface fluid/gas CBIE with DIM correction and plane-wave incidence on a fixed full-3D mesh. Frequencies and training_frequencies are in Hz, sound_speed in m/s, and angles in radians from +x with azimuth from +y toward +z. Returns a sweep of complex backscatter amplitudes and target strengths in the supplied query order.

Train a bounded orthonormal solution basis using full Float64 solves, then freeze it before evaluating queries. Every query assembles its own equations and basis images. Both original and row-scaled relative residuals must satisfy tolerance. Rank loss or failed acceptance triggers a full Float64 solve, checked against the same residual target. Queries never enrich the basis. capacity and maxbytes bound snapshot coefficient storage, not total assembly or process memory.

With return_diagnostics=true, return (sweep, diagnostics) as a named tuple. Diagnostics contain training and query reports, retained basis rank and bytes, and settings. Query reports identify reduced acceptance or full-solve fallback. Residual acceptance does not bound physical mesh error. Resolve the supplied mesh over the entire frequency range. Training cost can exceed the savings for short sweeps, and no automatic speedup is assumed. The callback overload is unchanged.

incidence_angle_sweep(solve, angles)

Call solve(angle) once per incident polar angle in radians and retain monostatic strength and complex amplitude. The callback supplies the fixed frequency and may return an ordinary solution or a components comparison.

incidence_angle_sweep(mfs, body, boundary, k, angles; n=default, m_max=default,
    offset=0.3*characteristic_radius, oversampling=1, rtol=1e-6,
    condition_limit=512, return_diagnostics=false)

Sample axisymmetric MFS backscatter at fixed exterior wavenumber k (inverse meters) for a Sphere, Spheroid, or straight Cylinder. Polar angles are radians from body-frame +x. Supports Rigid, PressureRelease, Impedance, and FluidFilled. Source placement, oversampling and quadrature follow mfs; fluid boundaries also accept offset_ext and offset_int, each defaulting to offset in meters.

Assemble and factor each Fourier mode once for all angles, including independent boundary-check operators and condition/rank diagnostics. Only one mode's matrices are retained at a time; coefficients and surface fields are discarded after sampling. Nonzero angles use modes 0:m_max; exactly zero uses only mode zero, as in mfs. No setup is cached across calls. Bent cylinders and full-surface MFS are not supported. Rigid straight cylinders with flat caps are also unsupported by axisymmetric MFS; use bem for that sharp-rim geometry.

Returns sampled angles, target strengths, and amplitudes. With return_diagnostics=true, returns (; sweep, diagnostics), where diagnostics[i] contains the solve and independent boundary residuals for angles[i], in the same form as diagnostics(mfs(...)). Checks are computed in either case; condition_limit=0 skips the condition/rank SVD.

incidence_angle_sweep(body::Union{RevolvedBody,Torus,LoftedBody,Ellipsoid,Superellipsoid},
    boundary, k, angles; method, kwargs...)

Sample BEM backscatter on a generated geometry. Revolved bodies and tori default to axisymmetric solves, reusing rigid/soft operators across angles. Other bodies default to full BEM, reusing the generated surface and its boundary operators.

incidence_angle_sweep(body::Cylinder, boundary::Union{Rigid,PressureRelease,Impedance}, k, angles;
    n=default, m_max=default, rtol=1e-5)

Sample axisymmetric BEM backscatter at fixed exterior wavenumber k in inverse meters, for a straight (unbent) Cylinder. Each Fourier mode's boundary operator depends only on the mesh, k and the mode, not the incidence angle, so it is assembled and factorized once and reused for every angle; only the incident-field right-hand side is rebuilt per angle. m_max is therefore fixed for the whole sweep rather than resolved per angle as a single bem call would. A bent Cylinder needs bem(...; method=:full) instead. Returns a sweep result with target strengths and amplitudes.

Process all angles in batches of at most eight Fourier modes, releasing completed matrices and factors before assembling the next batch. Accumulate backscatter amplitudes without retaining all modes' factors or all angles' surface traces. If the summed far-field quadrature estimates indicate cancellation between batches, rebuild that angle's traces in bounded batches and use the combined-mode integral. This safeguard can require additional assembly for the affected angle.

incidence_angle_sweep(surface::Mesh, boundary::Union{Rigid,PressureRelease}, k, angles; kwargs...)

Sample full-3D BEM backscatter at fixed exterior wavenumber k in inverse meters. Polar angles are radians from +x, with fixed incidence_azimuth=0 by default. Reuse layer operators, their compression and the system operator within this call. Each angle gets an independent GMRES solve with the supplied tolerances.

Accepts formulation, compression, correction and gmres_kwargs as in bem. Returns sampled amplitudes and strengths. Operators are discarded after sampling. Subsequent calls assemble from their own inputs.

incidence_angle_sweep(surface::Mesh, material::FluidFilled, k, angles; kwargs...)
incidence_angle_sweep(surfaces, materials, k, angles; components=false, labels=nothing, kwargs...)

Sample fluid/gas full-3D BEM backscatter at fixed exterior wavenumber k in inverse meters. Polar angles are radians from +x; incidence_azimuth=0 sweeps the xy plane. Geometry validation, operators and factorization are reused within this call. A new call assembles from its supplied meshes, materials, frequency and solver options.

Accepts formulation, correction, equilibrate and condition_limit as in bem. The single-interface dense overload also accepts precision=:mixed and refinement, reusing the guarded factorization across angles. Promotion to ComplexF64 persists for the remaining angles in that call. Both fluid overloads also accept compression and gmres_kwargs, reusing the compressed operators and block preconditioner across incidence angles. For compressed solves, recycle_dimension=8 also retains a bounded solution subspace to initialize later angles. Set it to zero for independent GMRES starts. Retained solution/image pairs are capped at 64 MiB; dense solves do not use this storage. Every recycled solve checks the true scaled residual against the original right-hand side tolerance and retries from zero if necessary. Recycling is local to this call. Residual corrections share an attempt's maxiter budget; a fallback gets a fresh budget. Iteration diagnostics include all correction and fallback work. The multiple-interface overload also accepts parents and validation. With components=true, include each interface isolated in the exterior medium and their coherent complex sum, using the same solver options. labels supplies one name per interface. Each system is sampled separately to limit retained matrix storage.

Returns complex amplitudes and target strengths in a sweep result. Dense solution state is discarded after sampling.

Examples

aspect = incidence_angle_sweep(surfaces, materials, k, deg2rad.([60, 90, 120]);
    parents=[0, 1], components=true, labels=["flesh", "bladder"])

incidence_angle_sweep(body::Irregular, boundary::AbstractBoundaryCondition, k, angles; kwargs...)

Sample Fourier-matching backscatter at fixed exterior wavenumber k, reusing the conformal mapping and the boundary-matching transition operator (see Fourier matching) across all angles, since neither depends on incidence angle. Each angle then only needs a cheap incident-coefficient recompute and matrix-vector solve, not the expensive boundary-matching quadrature that dominates a single fourier call.

Accepts continuation_steps, mapping_order, m_max, n_max, rtol and maxevals as in fourier. Returns a sweep result with amplitudes and target strengths.

incidence_angle_sweep(body::Spheroid, boundary::Union{SolidElastic, Shelled{ElasticLayer}}, k, angles; kwargs...)

Sample the elastic prolate spheroid or shell backscatter at fixed exterior wavenumber k. The transition matrices do not depend on direction, so each azimuthal order is computed once and reused for every angle. Accepts m_max, n_max and check as in tmatrix, and method = :volume samples the volume FEM instead. Returns a sweep result.

incidence_angle_sweep(body::Union{Sphere,Spheroid}, boundary, k, angles; method=:volume, incidence_azimuth=0, kwargs...)

Sample full-3D volume FEM backscatter at fixed exterior wavenumber k. The mesh, matrix and its factorization do not depend on the incident direction, so they are built once and each angle only needs a new load and solve. Accepts the keywords of fem(...; method = :volume), with angles the polar incidence angles in radians. Returns a sweep result.

method=:axisymmetric instead samples axisymmetric BEM for a Rigid/PressureRelease/ Impedance boundary, reusing each Fourier mode's factorized operator across angles; see incidence_angle_sweep(::Cylinder, ::Union{Rigid,PressureRelease,Impedance}, ...). It accepts n, m_max and rtol instead of the volume-FEM keywords.

method=:modal supports a full-coupling FluidFilled spheroid. It evaluates each azimuthal order's spheroidal basis once across all angles while retaining the existing coupling solve for each incident direction. Fix m_max, n_max, n_quad, and precision within a sweep.

incidence_angle_sweep(bodies::AbstractVector{<:AbstractBody}, materials::AbstractVector, k, angles; kwargs...)

Volume FEM backscatter of coupled fluid and elastic regions, as in fem(bodies, materials, k; method = :volume), with one mesh and factorization for all angles.

bistatic_sweep(solution, angles; azimuth=0)

Sample an observation cut from retained BEM, MFS, meridian/shell FEM or volume FEM surface/field data, including full-3D, coupled-region, free_surface solutions or components comparisons. No re-solves. For axisymmetric BEM/MFS, meridian/shell FEM and full/coupled-region BEM, angles are radians from +x toward the azimuthal direction, with π/2 along +y and 3π/2 along -y at azimuth zero. Volume FEM and free_surface results instead use their own scattering_amplitude convention, radians from +z with azimuth measured in the xy-plane from +x. Retain both target strength and complex amplitude.

bistatic_map(solution, thetas, phis)

Sample target strength on a polar/azimuthal observation grid in radians without re-solving. Supported for axisymmetric and full-3D BEM/MFS, coupled-region BEM, shell FEM, volume FEM and free_surface solutions. See bistatic_sweep for the angle convention, which differs between the axisymmetric/full-BEM and volume FEM/free-surface families.