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.

IncidentField

Supertype of incident excitations for solvers that accept an incident keyword. See PlaneWave, SphericalWave and BesselBeam.

PlaneWave()

A unit-amplitude plane wave, exp(ikz) along its own propagation axis. The default incident field wherever an incident keyword exists.

SphericalWave(range)

A unit-amplitude point-source spherical wave, exp(ikR)/R, from a source range [m] from the expansion origin, on the observation axis.

BesselBeam(angle)

A unit-amplitude, non-diffracting zeroth-order Bessel beam on the observation axis, 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.

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.

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 of two layers) 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, its own radius_ratio must be strictly greater than the enclosing Shelled's.

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-like shell layer (Feuillade and Nero, 1998), e.g. the flesh surrounding a fish's swimbladder. Used as the outer layer of a LayeredMaterial.

• 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 and kinematic_viscosity_shear are the kinematic bulk and shear viscosities in m²/s. Set both to 0.0 for the lossless (purely elastic) limit.

See Modal series.

LayeredMaterial(outer, inner, radius_ratio)

Two concentric shell material layers, outer (ViscousLayer or ElasticLayer) enclosing inner (ElasticLayer). radius_ratio is the inner layer's own outer radius over the outer layer's outer radius, in (0,1). Used as the material of a Shelled whose interior is enclosed by two layers rather than one, e.g. a viscous-flesh-over-elastic-wall swimbladder model (Feuillade and Nero, 1998):

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). 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. 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, and a shell solve is repeated with both reduced by 2 and warns when the amplitude changes by more than 1%. Pass check = false to skip the repeat. Post-process with target_strength or scattering_amplitude.

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) backscattering amplitude on a supplied full-3D surface, retaining its actual shape, normals and any endcaps: the same surface integral the canonical-shape methods evaluate in closed form, f = Rc·(k/2π) ∫∫_illuminated (n̂·d̂) e^{2ik d̂·y} dS (Rc from reflection_coefficient, d̂ the incident direction, illuminated where n̂·d̂ > 0), now a direct sum over surface's own quadrature nodes. Reproduces kirchhoff(Sphere/Spheroid, ...) to mesh-discretization accuracy when fed a matching generated mesh. Illumination is the local outward normal against the incident direction, not a hidden-surface check, so a concave surface can misclassify a self-shadowed region as illuminated. Returns a KirchhoffSolution.

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 only axial incidence. Cylinder/Spheroid support general incidence_angle.

• :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 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.

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

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::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. Axial incidence only (the underlying engine/shell_bem.jl solve has no oblique variant).

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.

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(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.

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, 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.

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 a unit plane wave traveling along +x; pressure is not available for a SphericalWave or BesselBeam incident field. 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.

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(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. Non-structural radial/meridian FEM rejects observation keywords with ArgumentError.

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. 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. Cylinder radial and meridian FEM paths retain only target strength and throw ArgumentError for complex amplitude.

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; prescribed fields retain their supplied 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). It is ignored otherwise.

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 and Fourier matching. Modal and Kirchhoff solutions return nothing.

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::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.

Examples

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

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.

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::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. 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.

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.