propagationPaths

R2026b

Calculate underwater propagation paths using Bellhop

Since R2026b

collapse all in page

    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.

    example

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

    Examples

    collapse all

    This example uses:

    Open Live Script

    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)

    Figure Bellhop Eigen Rays contains 2 axes objects. Axes object 1 with title SSP, xlabel Sound speed (m/s), ylabel Depth (m) contains an object of type line. Axes object 2 with title Eigen Rays, xlabel Range (km) contains 20 objects of type line. One or more of the lines displays its values using only markers These objects represent Source, Receiver.

    Input Arguments

    collapse all

    The bellhopModel object that interfaces with Bellhop.

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

    Data Types: double | single

    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.

    Data Types: double | single

    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.

    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

    collapse all

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

    Column NameValue
    PathLossThe propagation loss along the path in dB, returned as a scalar. Loss is caused by spreading, volume attenuation, and top and bottom boundary reflections.
    PathDelayThe delay of the propagation path in seconds, returned as a scalar.
    PhaseShiftThe cumulative phase shift of the propagation path in degrees, returned as a scalar. Phase shifts are caused by top and bottom boundary reflections.
    AngleOfDepartureThe 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.
    AngleOfArrivalThe 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.
    NumSurfaceReflectionsThe number of times the path reflected off the sea surface.
    NumBottomReflectionsThe number of times the path reflected off the sea bottom.

    Version History

    Introduced in R2026b

    See Also

    External Websites