Reading from Bellhop text files

Reader functions for aubellhop.

This file provides a collection of reading methods for both input and output Bellhop files.

Reading the environment file has substantial logic when relies on the state of the environment information it is passed. Therefore, this is managed by class EnvironmentReader(), used internally by the Environment class via its class method Environment.from_file().

Subsequent files (ssp, bty, ati, brc, trc) are read automatically, but public interfaces are provided for these for the purposes of mix and matching data if desired.

Finally, readers are also provides for output files for rays, arrivals, and binary shd files. Again, these are used automatically by aubellhop after executing a computation, but public methods are provides to help with testing and verification.

class aubellhop.readers.EnvironmentReader(env: Environment, fname: str)

Read and parse Bellhop environment files.

Although this class is only used for one task, the use of a class provides the clearest code interface compared to nested functions, which either implicitly set dict parameters, or have many repeated and superfluous arguments as dicts are passed in and returned at each stage.

read() → Environment

Do the reading…

aubellhop.readers.read_ssp(fname: str, depths: list[float] | ndarray[tuple[Any, ...], dtype[float64]] | DataFrame | None = None) → ndarray[tuple[Any, ...], dtype[float64]] | DataFrame

Read a 2D sound speed profile (.ssp) file used by BELLHOP.

This function reads BELLHOP’s .ssp files which contain range-dependent sound speed profiles. The file format is: - Line 1: Number of range profiles (NPROFILES) - Line 2: Range coordinates in km (space-separated) - Line 3+: Sound speed values, one line per depth point across all ranges

Parameters:

fname (str) – Path to .ssp file (with or without .ssp extension)

Returns:

For single-profile files: numpy array with [depth, soundspeed] pairs; for multi-profile files: pandas DataFrame with range-dependent sound speed data

Return type:

numpy.ndarray or pandas.DataFrame

Notes

Return format:

• Single-profile files (1 range): Returns a 2D numpy array with [depth, soundspeed] pairs, compatible with the Environment() soundspeed parameter.

• Multi-profile files (>1 ranges): Returns a pandas DataFrame where:

  • Columns: Range coordinates (in meters, converted from km in file)

  • Index: Depth indices (0, 1, 2, … for each depth level in the file)

  • Values: Sound speeds (m/s)

  This DataFrame can be directly assigned to the Environment() soundspeed parameter for range-dependent acoustic modeling.

Note on depths: For multi-profile files, depth indices are used (0, 1, 2, …) since the actual depth coordinates come from the associated BELLHOP .env file. Users can modify the DataFrame index if actual depth values are known.

Examples

>>> import aubellhop as bh
>>> # Single-profile file
>>> ssp1 = bh.read_ssp("single_profile.ssp")  # Returns numpy array
>>> env = bh.Environment()
>>> env["soundspeed"] = ssp1
>>>
>>> # Multi-profile file
>>> ssp2 = bh.read_ssp("tests/MunkB_geo_rot/MunkB_geo_rot.ssp")  # Returns DataFrame
>>> env = bh.Environment()
>>> env["soundspeed"] = ssp2  # Range-dependent sound speed

File format example:

30
-50 -5 -1 -.8 -.75 -.6 -.4 -.2 0 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 2.2 2.4 2.6 2.8 3.0 3.2 3.4 3.6 3.8 4.0 10.0
1500 1500 1548.52 1530.29 1526.69 1517.78 1509.49 1504.30 1501.38 1500.14 1500.12 1501.02 1502.57 1504.62 1507.02 1509.69 1512.55 1515.56 1518.67 1521.85 1525.10 1528.38 1531.70 1535.04 1538.39 1541.76 1545.14 1548.52 1551.91 1551.91
1500 1500 1548.52 1530.29 1526.69 1517.78 1509.49 1504.30 1501.38 1500.14 1500.12 1501.02 1502.57 1504.62 1507.02 1509.69 1512.55 1515.56 1518.67 1521.85 1525.10 1528.38 1531.70 1535.04 1538.39 1541.76 1545.14 1548.52 1551.91 1551.91

aubellhop.readers.read_ssp_3d(fname: str) → dict[str, ndarray]

Read a 3D sound speed profile (.ssp) file used by BELLHOP3D and return a 3D Numpy array.

This function reads BELLHOP’s .ssp files which contain range-dependent sound speed profiles. The file format is: - Line 1: Nx: Number of coordinates in the range (x) direction - Line 2: Range coordinates in km (space-separated) - Line 3: Ny: Number of coordinates in the crossrange (y) direction - Line 4: Crossrange coordinates in km (space-separated) - Line 5: Nz: Number of coordinates in the depth (z) direction - Line 6: Depth coordinates in km (space-separated) - Line 7+: Sound speed values, one line per crossrange and depth across all ranges

(i.e., each line has Nx number of values and there are Ny*Nz lines)

aubellhop.readers.read_ati(fname: str) → tuple[ndarray[tuple[Any, ...], dtype[float64]], str]

Read an altimetry file used by Bellhop.

aubellhop.readers.read_bty(fname: str) → tuple[ndarray[tuple[Any, ...], dtype[float64]], str]

Read a bathymetry file used by Bellhop.

aubellhop.readers.read_ati_3d(fname: str) → dict[str, ndarray]

Read an altimetry file used by Bellhop.

aubellhop.readers.read_bty_3d(fname: str) → dict[str, ndarray]

Read a bathymetry file used by Bellhop.

aubellhop.readers.read_sbp(fname: str) → ndarray[tuple[Any, ...], dtype[float64]]

Read an source beam patterm (.sbp) file used by BELLHOP.

The file format is: - Line 1: Number of points - Line 2+: Angle (deg) and power (dB) pairs

Parameters:

fname (str) – Path to .sbp file (with or without extension)

Returns:

Numpy array with [angle, power] pairs

Return type:

numpy.ndarray

aubellhop.readers.read_brc(fname: str) → ndarray[tuple[Any, ...], dtype[float64]]

Read a BRC file and return array of reflection coefficients.

This function reads BELLHOP’s .brc files which define the reflection coefficient data. The file format is: - Line 1: Number of points - Line 2+: THETA(j) RMAG(j) RPHASE(j)

Where: - THETA(): Angle (degrees) - RMAG(): Magnitude of reflection coefficient - RPHASE(): Phase of reflection coefficient (degrees)

Parameters:

fname (str) – Path to .brc/.trc file (extension required)

Returns:

Numpy array with [theta, rmag, rphase] triplets compatible with Environment()

Return type:

numpy.ndarray

Notes

The returned array can be assigned to env[“bottom_reflection_coefficient”]. The equivalent read_trc() data would be assigned to env[“surface_reflection_coefficient”].

File format example

3
0.0   1.00  180.0
45.0  0.95  175.0
90.0  0.90  170.0

Example

>>> import aubellhop as bh
>>> import aubellhop.readers as bhr
>>> brc = bhr.read_refl_coeff("tests/MunkB_geo_rot/MunkB_geo_rot.brc")
>>> env = bh.Environment()
>>> env["bottom_reflection_coefficient"] = brc
>>> arrivals = bh.calculate_arrivals(env)

aubellhop.readers.read_trc(fname: str) → ndarray[tuple[Any, ...], dtype[float64]]

Read a TRC file and return array of reflection coefficients.

See equivalent read_brc function for documentation.

aubellhop.readers.read_arrivals(fname: str) → DataFrame

Read Bellhop arrivals file and parse data into a high level data structure

aubellhop.readers.read_rays(fname: str, **kwargs) → DataFrame

Read Bellhop rays file and parse data into a high level data structure

aubellhop.readers.read_shd(fname: str) → DataFrame

Read Bellhop shd file and parse data into a high level data structure

class aubellhop.readers.BellhopOutputReader(filename: str)

Read and parse Bellhop output files.

read_arrivals() → DataFrame

Read Bellhop arrivals file and parse data into a high level data structure

read_shd() → DataFrame

Read Bellhop shd file and parse data into a high level data structure

read_rays(dim: int | None = None) → DataFrame

Read Bellhop rays file and parse data into a high level data structure

Parameters:

dim ({2, 3} or None) – Spatial dimension. If None, inferred from the file header.

Raises:

ValueError – if is_2d is not provided and parsing file header fails.: