Reading from Bellhop text files

These functions are automatically imported into the parent bellhop module.

bellhop.readers.read_env(fname: str) → Environment

Read a 2D underwater environment from a BELLHOP .env file.

This function parses a BELLHOP .env file and returns a Python data structure that is compatible with create_env(). This enables round-trip testing and compatibility between file-based and programmatic environment definitions.

Parameters:

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

Returns:

Environment dictionary compatible with create_env()

Return type:

dict

Notes

Unit conversions performed:

• Receiver ranges: km → m

• Bottom density: g/cm³ → kg/m³

• All other units preserved as in ENV file

Examples

>>> import bellhop as bh
>>> env = bh.read_env('examples/Munk/MunkB_ray.env')
>>> print(env['name'])
'Munk profile'
>>> print(env['frequency'])
50.0

>>> # Use with existing functions
>>> checked_env = bh.check_env(env)
>>> rays = bh.compute_rays(env)

>>> # Round-trip compatibility
>>> env_orig = bh.create_env(name="test", frequency=100)
>>> # ... write to file via BELLHOP ...
>>> env_read = bh.read_env("test.env")
>>> assert env_read['frequency'] == env_orig['frequency']

class bellhop.readers.EnvironmentReader(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…

bellhop.readers.read_ssp(fname: str, depths: List[float] | numpy.typing.NDArray.numpy.float64 | pandas.DataFrame | None = None) → numpy.typing.NDArray.numpy.float64 | pandas.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 create_env() 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 create_env() 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 bellhop as bh
>>> # Single-profile file
>>> ssp1 = bh.read_ssp("single_profile.ssp")  # Returns numpy array
>>> env = bh.create_env()
>>> env["soundspeed"] = ssp1
>>>
>>> # Multi-profile file
>>> ssp2 = bh.read_ssp("tests/MunkB_geo_rot/MunkB_geo_rot.ssp")  # Returns DataFrame
>>> env = bh.create_env()
>>> 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

bellhop.readers.read_bty(fname: str) → Tuple[numpy.typing.NDArray.numpy.float64, str]

Read a bathymetry file used by Bellhop.

bellhop.readers.read_ati(fname: str) → Tuple[numpy.typing.NDArray.numpy.float64, str]

Read an altimetry file used by Bellhop.

bellhop.readers.read_ati_bty(fname: str) → Tuple[numpy.typing.NDArray.numpy.float64, str]

Read an altimetry (.ati) or bathymetry (.bty) file used by BELLHOP.

This function reads BELLHOP’s .bty files which define the bottom depth profile. The file format is: - Line 1: Interpolation type (‘L’ for linear, ‘C’ for curvilinear) - Line 2: Number of points - Line 3+: Range (km) and depth (m) pairs

Parameters:

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

Returns:

Numpy array with [range, depth] pairs compatible with create_env()

Return type:

numpy.ndarray

Notes

The returned array can be assigned to env[“depth”] for range-dependent bathymetry.

Examples:

>>> import bellhop as bh
>>> bty,bty_interp = bh.read_bty("tests/MunkB_geo_rot/MunkB_geo_rot.bty")
>>> env = bh.create_env()
>>> env["depth"] = bty
>>> env["depth_interp"] = bty_interp
>>> arrivals = bh.calculate_arrivals(env)

File format example:

'L'
5
0 3000
10 3000
20 500
30 3000
100 3000

bellhop.readers.read_sbp(fname: str) → numpy.typing.NDArray.numpy.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

bellhop.readers.read_brc(fname: str) → numpy.typing.NDArray.numpy.float64

Read a BRC file and return array of reflection coefficients.

See read_refl_coeff for documentation, but use this function for extension checkking.

bellhop.readers.read_trc(fname: str) → numpy.typing.NDArray.numpy.float64

Read a TRC file and return array of reflection coefficients.

See read_refl_coeff for documentation, but use this function for extension checkking.

bellhop.readers.read_refl_coeff(fname: str) → numpy.typing.NDArray.numpy.float64

Read a reflection coefficient (.brc/.trc) file used by BELLHOP.

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 create_env()

Return type:

numpy.ndarray

Notes

The returned array can be assigned to env[“bottom_reflection_coefficient”] or env[“surface_reflection_coefficient”] .

Examples

>>> import bellhop as bh
>>> brc = bh.read_refl_coeff("tests/MunkB_geo_rot/MunkB_geo_rot.brc")
>>> env = bh.create_env()
>>> env["bottom_reflection_coefficient"] = brc
>>> arrivals = bh.calculate_arrivals(env)

File format example:

3
0.0   1.00  180.0
45.0  0.95  175.0
90.0  0.90  170.0

bellhop.readers.read_arrivals(fname: str) → pandas.DataFrame

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

bellhop.readers.read_shd(fname: str) → pandas.DataFrame

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

bellhop.readers.read_rays(fname: str) → pandas.DataFrame

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