propagationPaths

R2026b

Calculate underwater propagation paths using Bellhop

Since R2026b

Syntax

propPaths = propagationPaths(bhModel,fc,srcLocation,rxLocation)

propagationPaths(bhModel,fc,srcLocation,rxLocation)

Description

Add-On Required: This feature requires the Underwater Acoustic Channels add-on.

propPaths = propagationPaths(bhModel,fc,srcLocation,rxLocation) returns the propagation paths between an underwater source and receiver.

propagationPaths(bhModel,fc,srcLocation,rxLocation) with no output arguments plots eigenrays between an underwater source and receiver.

Examples

Calculate and Plot Propagation Paths Using Bellhop

To run this example, you must have Bellhop installed, and you must also configure MATLAB with the Bellhop executable path by using the bellhopConfiguration function.

Create a bellhopModel object with the default configuration.

bhModel = bellhopModel

bhModel = 
  bellhopModel handle with properties:

                       SoundSpeed: [27×1 double]
                  SoundSpeedDepth: [27×1 double]
           SSPInterpolationMethod: "linear"
          BottomBathymetryProfile: "flat"
     BottomReflectionCoefficients: [181×2 double]
          SurfaceAltimetryProfile: "flat"
    SurfaceReflectionCoefficients: -1

  Show all properties

Calculate the propagation paths from a source at (0, 40, 1000) m with an operating frequency of 1000 Hz to a receiver at (20000, 35000, 1500) m.

fc = 1000;
srcLocation = [0;40;1e3];
rxLocation = [20e3;35e3;1.5e3];
propPaths = propagationPaths(bhModel,fc,srcLocation,rxLocation)

propPaths = 9×7 table
    PathLoss    PathDelay    PhaseShift    AngleOfDeparture    AngleOfArrival    NumSurfaceReflections    NumBottomReflections
    ________    _________    __________    ________________    ______________    _____________________    ____________________

     87.628       26.84            90        0    -2.8651       0    -3.4277               0                       0          
     89.403      26.791             0        0     9.7373       0    -9.9433               0                       0          
     96.489      27.378        108.71        0     17.501       0     17.612               1                       1          
     96.834       27.18        94.175        0    -16.733       0     -16.82               1                       1          
     97.168      27.752       -38.287        0    -19.547       0     19.641               2                       1          
     98.455      26.874       -125.13        0     15.284       0    -15.376               0                       1          
     111.64      28.868        162.11        0     25.236       0    -25.301               1                       2          
     113.84      29.425       -14.018        0    -27.367       0    -27.427               2                       2          
     114.57      29.738       -12.728        0     28.364       0     28.421               2                       2          

Plot the eigenrays at the receiver location.

propagationPaths(bhModel,fc,srcLocation,rxLocation)

Input Arguments

bhModel — bellhopModel object

bellhopModel

The bellhopModel object that interfaces with Bellhop.

fc — Operating frequency of source

positive scalar

Operating frequency of the source in Hz, specified as a positive scalar.

Data Types: double | single

srcLocation — Source location in underwater environment

3-by-1 column vector

Source location in underwater environment, specified as a 3-by-1 column vector. Specify the location as an (x, y, z) position in the three-dimensional environment, where x, y, and z are global Cartesian coordinates. The z-coordinate is positive in the downward direction. The z value must be greater than 0 and must not exceed the maximum depth specified by the SoundSpeedProfile property of bhModel. The propagationPaths function internally converts coordinates to a local cylindrical coordinate system. For more information on coordinate systems, see Global and Local Coordinate Systems (Phased Array System Toolbox).

Data Types: double | single

rxLocation — Receiver location in underwater environment

3-by-1 column vector

Receiver location in underwater environment, specified as a 3-by-1 column vector. Specify the location as an (x, y, z) position in the three-dimensional environment, where x, y, and z are global Cartesian coordinates. The z-coordinate is positive in the downward direction. The z value must be greater than 0 and must not exceed the maximum depth specified by the SoundSpeedProfile property of bhModel. The propagationPaths function internally converts coordinates to a local cylindrical coordinate system. For more information on coordinate systems, see Global and Local Coordinate Systems (Phased Array System Toolbox).

The range between the srcLocation and rxLocation must be less than or equal to the maximum range defined by the RayTraceRangeLimit property of bhModel.

Data Types: double | single

Output Arguments

propPaths — Propagation paths between source and receiver

table

Propagation paths between the source and receiver, returned as a table. The table has seven columns with one row per path:

Column Name	Value
PathLoss	The propagation loss along the path in dB, returned as a scalar. Loss is caused by spreading, volume attenuation, and top and bottom boundary reflections.
PathDelay	The delay of the propagation path in seconds, returned as a scalar.
PhaseShift	The cumulative phase shift of the propagation path in degrees, returned as a scalar. Phase shifts are caused by top and bottom boundary reflections.
AngleOfDeparture	The angle of departure of the propagation path in degrees, returned as a two-column vector. The first column represents azimuth and the second column represents elevation.
AngleOfArrival	The angle of arrival of the propagation path in degrees, returned as a two-column vector. The first column represents azimuth and the second column represents elevation.
NumSurfaceReflections	The number of times the path reflected off the sea surface.
NumBottomReflections	The number of times the path reflected off the sea bottom.

Limitations

• The bellhopModel object uses a temporary directory to store Bellhop input files while propagationPaths is running. The Fortran implementation of Bellhop errors if the file path length exceeds 80 characters. If you encounter this error, change the temporary directory to a path with fewer characters. For more information, see How do I change the Temporary Directory that MATLAB uses?.

Version History

Introduced in R2026b