Plotting Reference

Plotting functions (bokeh)

Plotting functions for aubellhop.

class aubellhop.plot.Any(*args, **kwargs)[source]

Special type indicating an unconstrained type.

  • Any is compatible with every type.

  • Any assumed to have all methods.

  • All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class aubellhop.plot.Environment(name: str = 'bellhop/python default', _from_file: str | None = None, dimension: str = BHStrings.two_d, _dimension: int = 2, frequency: float = 25000.0, _num_media: int = 1, soundspeed: float | Any = 1500.0, soundspeed_interp: str = BHStrings.linear, _mesh_npts: int = 0, _depth_sigma: float = 0.0, _depth_max: float | None = None, _range_max: float | None = None, _bathymetry: str = BHStrings.flat, _altimetry: str = BHStrings.flat, _sbp_file: str = BHStrings.default, bottom_depth: float | Any = 25.0, bottom_interp: str = BHStrings.linear, _bottom_depth: float | None = None, bottom_soundspeed: float = 1500.0, _bottom_soundspeed_shear: float = 0.0, bottom_density: float = 1000.0, bottom_attenuation: float | None = None, _bottom_attenuation_shear: float | None = None, bottom_roughness: float = 0.0, bottom_beta: float | None = None, bottom_transition_freq: float | None = None, bottom_boundary_condition: str = BHStrings.acousto_elastic, bottom_reflection_coefficient: Any | None = None, bottom_grain_size: float | None = None, surface_depth: Any | None = None, surface_interp: str = BHStrings.linear, surface_boundary_condition: str = BHStrings.vacuum, surface_reflection_coefficient: Any | None = None, surface_soundspeed: float = 1500.0, _surface_soundspeed_shear: float = 0.0, surface_density: float = 1000.0, surface_attenuation: float | None = None, _surface_attenuation_shear: float | None = None, _surface_min: float | None = None, surface_min: float | None = None, source_type: str = BHStrings.default, source_range: float | Any = 0.0, source_cross_range: float | Any = 0.0, source_depth: float | Any = 5.0, source_ndepth: int | None = None, source_nrange: int | None = None, source_ncrossrange: int | None = None, source_directionality: Any | None = None, _source_num: int = 0, receiver_depth: float | Any = 10.0, receiver_range: float | Any = 1000.0, receiver_bearing: float | Any = 0.0, receiver_ndepth: int | None = None, receiver_nrange: int | None = None, receiver_nbearing: int | None = None, _receiver_num: int = 0, beam_type: str = BHStrings.default, beam_angle_min: float | None = None, beam_angle_max: float | None = None, beam_bearing_min: float | None = None, beam_bearing_max: float | None = None, beam_num: int = 0, beam_bearing_num: int = 0, single_beam_index: int | None = None, _single_beam: str = BHStrings.default, beam_width_type: str | None = None, beam_reflection_curvature_change: str | None = None, beam_reflection_shift: str | None = None, beam_epsilon_multipler: float | None = None, beam_range_loop: float | None = None, beam_images_num: int | None = None, beam_window: int | None = None, beam_component: str | None = None, simulation_depth: float | None = None, simulation_range: float | None = None, simulation_cross_range: float | None = None, simulation_depth_scale: float | None = None, simulation_range_scale: float | None = None, simulation_cross_range_scale: float | None = None, simulation_cross_range_min: float | None = None, step_size: float | None = 0.0, grid_type: str = BHStrings.default, task: str | None = None, interference_mode: str | None = None, volume_attenuation: str = BHStrings.none, attenuation_units: str = BHStrings.frequency_dependent, biological_layer_parameters: Any | None = None, _fg_salinity: float | None = None, _fg_temperature: float | None = None, _fg_pH: float | None = None, _fg_depth: float | None = None, comment_pad: int = 50)[source]

Dataclass for underwater acoustic environment configuration.

This class provides automatic validation of environment parameters, eliminating the need for manual checking of option validity.

These entries are either intended to be set or edited by the user, or with _ prefix are internal state read from a .env file or inferred by other data. Some others are ignored.

Parameters:

**kv (dict) – Keyword arguments for environment configuration.

Returns:

env – A new underwater environment dictionary.

Return type:

dict

Raises:

ValueError – If any parameter value is invalid according to BELLHOP constraints.

Example

To see all the parameters available and their default values:

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> print(env)

The environment parameters may be changed by passing keyword arguments or modified later using dictionary notation:

>>> import aubellhop as bh
>>> env = bh.Environment(bottom_depth=40, soundspeed=1540)
>>> print(env)
>>> env.bottom_depth = 25
>>> env.bottom_soundspeed = 1800
>>> print(env)

The default environment has a constant sound speed. A depth dependent sound speed profile be provided as a Nx2 array of (depth, sound speed):

>>> import aubellhop as bh
>>> env = bh.Environment(bottom_depth=20,
>>>         soundspeed=[[0,1540], [5,1535], [10,1535], [20,1530]])

A range-and-depth dependent sound speed profile can be provided as a Pandas frame:

>>> import aubellhop as bh
>>> import pandas as pd
>>> ssp2 = pd.DataFrame({
>>>       0: [1540, 1530, 1532, 1533],     # profile at 0 m range
>>>     100: [1540, 1535, 1530, 1533],     # profile at 100 m range
>>>     200: [1530, 1520, 1522, 1525] },   # profile at 200 m range
>>>     index=[0, 10, 20, 30])             # depths of the profile entries in m
>>> env = bh.Environment(bottom_depth=20, soundspeed=ssp2)

The default environment has a constant water depth. A range dependent bathymetry can be provided as a Nx2 array of (range, water depth):

>>> import aubellhop as bh
>>> env = bh.Environment(bottom_depth=[[0,20], [300,10], [500,18], [1000,15]])
name: str = 'bellhop/python default'
dimension: str = '2D'
frequency: float = 25000.0
soundspeed: float | Any = 1500.0
soundspeed_interp: str = 'linear'
bottom_depth: float | Any = 25.0
bottom_interp: str = 'linear'
bottom_soundspeed: float = 1500.0
bottom_density: float = 1000.0
bottom_attenuation: float | None = None
bottom_roughness: float = 0.0
bottom_beta: float | None = None
bottom_transition_freq: float | None = None
bottom_boundary_condition: str = 'acousto-elastic'
bottom_reflection_coefficient: Any | None = None
bottom_grain_size: float | None = None
surface_depth: Any | None = None
surface_interp: str = 'linear'
surface_boundary_condition: str = 'vacuum'
surface_reflection_coefficient: Any | None = None
surface_soundspeed: float = 1500.0
surface_density: float = 1000.0
surface_attenuation: float | None = None
surface_min: float | None = None
source_type: str = 'default'
source_range: float | Any = 0.0
source_cross_range: float | Any = 0.0
source_depth: float | Any = 5.0
source_ndepth: int | None = None
source_nrange: int | None = None
source_ncrossrange: int | None = None
source_directionality: Any | None = None
receiver_depth: float | Any = 10.0
receiver_range: float | Any = 1000.0
receiver_bearing: float | Any = 0.0
receiver_ndepth: int | None = None
receiver_nrange: int | None = None
receiver_nbearing: int | None = None
beam_type: str = 'default'
beam_angle_min: float | None = None
beam_angle_max: float | None = None
beam_bearing_min: float | None = None
beam_bearing_max: float | None = None
beam_num: int = 0
beam_bearing_num: int = 0
single_beam_index: int | None = None
beam_width_type: str | None = None
beam_reflection_curvature_change: str | None = None
beam_reflection_shift: str | None = None
beam_epsilon_multipler: float | None = None
beam_range_loop: float | None = None
beam_images_num: int | None = None
beam_window: int | None = None
beam_component: str | None = None
simulation_depth: float | None = None
simulation_range: float | None = None
simulation_cross_range: float | None = None
simulation_depth_scale: float | None = None
simulation_range_scale: float | None = None
simulation_cross_range_scale: float | None = None
simulation_cross_range_min: float | None = None
step_size: float | None = 0.0
grid_type: str = 'default'
task: str | None = None
interference_mode: str | None = None
volume_attenuation: str = 'none'
attenuation_units: str = 'frequency dependent'
biological_layer_parameters: Any | None = None
comment_pad: int = 50
classmethod from_file(fname: str) → Environment[source]

Create an Environment from an .env file.

classmethod from_dict(data: dict[str, Any]) → Environment[source]

Create Environment from dictionary.

Unlike Environment(**data), unknown fields are ignored (with a warning message).

to_file(fname: str, task: str | None = None) → str[source]

Write a complete .env file for specifying a Bellhop simulation.

This is the user-facing file writer. It infers the file basename and resolves the task from the environment unless overridden.

Parameters:

  • fname (str) – Filename or filename base for the .env file. If no extension is provided, .env is appended.

  • task (str, optional) – Task string which defines the computation to run (e.g. “rays”, “eigenrays”, “arrivals”, “coherent”, “incoherent”, “semicoherent”). If not provided, this is inferred from env.task or env.interference_mode.

Returns:

The filename base (no extension) of the written file.

Return type:

str

reset() → Self[source]

Delete values for all user-facing parameters.

defaults() → Self[source]

Applies default values if not already set.

to_dict() → dict[str, Any][source]

Return a dictionary representation of the environment.

copy() → Environment[source]

Return a shallow copy of the environment.

unwrap(*keys: str) → list[Environment][source]

Return a list of Environment copies expanded over the given keys.

If multiple keys are provided, all combinations are produced. Each unwrapped Environment gets a unique .name derived from the parent name and the expanded field values.

set_fg_attenuation(salinity: float, temperature: float, pH: float, depth: float) → Self[source]

Interface to set Francois-Garrison volume attenuation parameters.

check() → Self[source]

Finalise environment parameters and perform assertion checks.

class aubellhop.plot.BHStrings(*values)[source]

String definitions to avoid hard-coding magic strings in the source code

This helps prevent typos and permits autocomplete (if your editor is smart enough).

default = 'default'
none = 'none'
two_d = '2D'
two_half_d = '2.5D'
three_d = '3D'
linear = 'linear'
spline = 'spline'
pchip = 'pchip'
nlinear = 'nlinear'
quadrilateral = 'quadrilateral'
hexahedral = 'hexahedral'
curvilinear = 'curvilinear'
vacuum = 'vacuum'
acousto_elastic = 'acousto-elastic'
rigid = 'rigid'
grain = 'grain'
from_file = 'from-file'
flat = 'flat'
line = 'line'
point = 'point'
cartesian = 'cartesian'
ray = 'ray'
hat_cartesian = 'hat-cartesian'
hat_ray = 'hat-ray'
gaussian_simple = 'gaussian-simple'
gaussian_cartesian = 'gaussian-cartesian'
gaussian_ray = 'gaussian-ray'
omnidirectional = 'omnidirectional'
single_beam = 'single beam'
rectilinear = 'rectilinear'
irregular = 'irregular'
thorp = 'thorp'
francois_garrison = 'francois-garrison'
biological = 'biological'
nepers_per_meter = 'nepers per meter'
frequency_dependent = 'frequency dependent'
db_per_meter = 'dB per meter'
db_per_wavelength = 'dB per wavelength'
quality_factor = 'quality factor'
loss_parameter = 'loss parameter'
rays = 'rays'
eigenrays = 'eigenrays'
arrivals = 'arrivals'
arrivals_b = 'arrivals-binary'
coherent = 'coherent'
incoherent = 'incoherent'
semicoherent = 'semicoherent'
class aubellhop.plot.figure(title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xtype='auto', ytype='auto', width=None, height=None, interactive=None)[source]

Create a new figure, and optionally automatically display it.

Parameters:

  • title (str, optional) – Figure title

  • xlabel (str, optional) – X-axis label

  • ylabel (str, optional) – Y-axis label

  • xlim (tuple of float, optional) – X-axis limits (min, max)

  • ylim (tuple of float, optional) – Y-axis limits (min, max)

  • xtype (str, default='auto') – X-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype (str, default='auto') – Y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width (int, optional) – Figure width in pixels

  • height (int, optional) – Figure height in pixels

  • interactive (bool, optional) – Enable interactive tools (pan, zoom, etc) for plot

Notes

This function can be used in standalone mode to create a figure:

>>> import arlpy.plot
>>> arlpy.plot.figure(title='Demo 1', width=500)
>>> arlpy.plot.plot([0,10], [0,10])

Or it can be used as a context manager to create, hold and display a figure:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 2', width=500):
>>>     arlpy.plot.plot([0,10], [0,10], color='blue', legend='A')
>>>     arlpy.plot.plot([10,0], [0,10], marker='o', color='green', legend='B')

It can even be used as a context manager to work with Bokeh functions directly:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 3', width=500) as f:
>>>     f.line([0,10], [0,10], line_color='blue')
>>>     f.square([3,7], [4,5], line_color='green', fill_color='yellow', size=10)
aubellhop.plot.plot_env(env: Environment, surface_color: str = 'dodgerblue', bottom_color: str = 'peru', source_color: str = 'orangered', receiver_color: str = 'midnightblue', receiver_plot: bool | None = None, **kwargs: Any) → None[source]

Plots a visual representation of the environment.

Parameters:

  • env (dict) – Environment description

  • surface_color (str, default='dodgerblue') – Color of the surface (see Bokeh colors)

  • bottom_color (str, default='peru') –

    Color of the bottom (see Bokeh colors)

  • source_color (str, default='orangered') –

    Color of transmitters (see Bokeh colors)

  • receiver_color (str, default='midnightblue') –

    Color of receivers (see Bokeh colors)

  • receiver_plot (bool, optional) – True to plot all receivers, False to not plot any receivers, None to automatically decide

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

The surface, bottom, transmitters (marker: ‘*’) and receivers (marker: ‘o’) are plotted in the environment. If receiver_plot is set to None and there are more than 2000 receivers, they are not plotted.

Examples

>>> import aubellhop as bh
>>> env = bh.Environment(bottom_depth=[[0, 40], [100, 30], [500, 35], [700, 20], [1000,45]])
>>> bh.plot_env(env)
aubellhop.plot.plot_ssp(env: Environment, **kwargs: Any) → None[source]

Plots the sound speed profile.

Parameters:

  • env (dict) – Environment description

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

If the sound speed profile is range-dependent, this function only plots the first profile.

Examples

>>> import aubellhop as bh
>>> env = bh.Environment(soundspeed=[[ 0, 1540], [10, 1530], [20, 1532], [25, 1533], [30, 1535]])
>>> bh.plot_ssp(env)
aubellhop.plot.plot_arrivals(arrivals: Any, dB: bool = False, color: str = 'blue', **kwargs: Any) → None[source]

Plots the arrival times and amplitudes.

Parameters:

  • arrivals (pandas.DataFrame) – Arrivals times (s) and coefficients

  • dB (bool, default=False) – True to plot in dB, False for linear scale

  • color (str, default='blue') –

    Line color (see Bokeh colors)

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> arrivals = bh.compute_arrivals(env)
>>> bh.plot_arrivals(arrivals)
aubellhop.plot.plot_rays(rays: DataFrame, env: Environment | None = None, invert_colors: bool = False, **kwargs: Any) → None[source]

Plots ray paths.

Parameters:

  • rays (pandas.DataFrame) – Ray paths

  • env (dict, optional) – Environment definition

  • invert_colors (bool, default=False) – False to use black for high intensity rays, True to use white

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

If environment definition is provided, it is overlayed over this plot using default parameters for bellhop.plot_env().

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> rays = bh.compute_eigenrays(env)
>>> bh.plot_rays(rays, width=1000)
aubellhop.plot.plot_transmission_loss(tloss: Any, env: Environment | None = None, **kwargs: Any) → None[source]

Plots transmission loss.

Parameters:

  • tloss (pandas.DataFrame) – Complex transmission loss

  • env (dict, optional) – Environment definition

  • **kwargs – Other keyword arguments applicable for bellhop.plot.image() are also supported

Notes

If environment definition is provided, it is overlayed over this plot using default parameters for bellhop.plot_env().

Examples

>>> import aubellhop as bh
>>> import numpy as np
>>> env = bh.Environment(
        receiver_depth=np.arange(0, 25),
        receiver_range=np.arange(0, 1000),
        beam_angle_min=-45,
        beam_angle_max=45
    )
>>> tloss = bh.compute_transmission_loss(env)
>>> bh.plot_transmission_loss(tloss, width=1000)

Plotting utilities (bokeh)

Easy-to-use plotting utilities for aubellhop based on Bokeh.

aubellhop.plotutils.theme(name: str) → None[source]

Set color theme.

Parameters:

name (str) – Name of theme

Examples

>>> import arlpy.plot
>>> arlpy.plot.theme('dark')
aubellhop.plotutils.figsize(x: int, y: int) → None[source]

Set the default figure size in pixels.

Parameters:

  • x (int) – Figure width

  • y (int) – Figure height

aubellhop.plotutils.interactive(b: bool) → None[source]

Set default interactivity for plots.

Parameters:

b (bool) – True to enable interactivity, False to disable it

aubellhop.plotutils.enable_javascript(b: bool) → None[source]

Enable/disable Javascript.

Parameters:

b (bool) – True to use Javascript, False to avoid use of Javascript

Notes

Jupyterlab does not support Javascript output. To avoid error messages, Javascript can be disabled using this call. This removes an optimization to replace non-interactive plots with static images, but other than that does not affect functionality.

aubellhop.plotutils.use_static_images(b: bool = True) → None[source]

Use static images instead of dynamic HTML/Javascript in Jupyter notebook.

Parameters:

b (bool, default=True) – True to use static images, False to use HTML/Javascript

Notes

Static images are useful when the notebook is to be exported as a markdown, LaTeX or PDF document, since dynamic HTML/Javascript is not rendered in these formats. When static images are used, all interactive functionality is disabled.

To use static images, you must have the following packages installed: selenium, pillow, phantomjs.

aubellhop.plotutils.hold(enable: bool = True) → bool | None[source]

Combine multiple plots into one.

Parameters:

enable (bool, default=True) – True to hold plot, False to release hold

Returns:

Old state of hold if enable is True

Return type:

bool or None

Examples

>>> import arlpy.plot
>>> oh = arlpy.plot.hold()
>>> arlpy.plot.plot([0,10], [0,10], color='blue', legend='A')
>>> arlpy.plot.plot([10,0], [0,10], marker='o', color='green', legend='B')
>>> arlpy.plot.hold(oh)
class aubellhop.plotutils.figure(title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xtype='auto', ytype='auto', width=None, height=None, interactive=None)[source]

Create a new figure, and optionally automatically display it.

Parameters:

  • title (str, optional) – Figure title

  • xlabel (str, optional) – X-axis label

  • ylabel (str, optional) – Y-axis label

  • xlim (tuple of float, optional) – X-axis limits (min, max)

  • ylim (tuple of float, optional) – Y-axis limits (min, max)

  • xtype (str, default='auto') – X-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype (str, default='auto') – Y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width (int, optional) – Figure width in pixels

  • height (int, optional) – Figure height in pixels

  • interactive (bool, optional) – Enable interactive tools (pan, zoom, etc) for plot

Notes

This function can be used in standalone mode to create a figure:

>>> import arlpy.plot
>>> arlpy.plot.figure(title='Demo 1', width=500)
>>> arlpy.plot.plot([0,10], [0,10])

Or it can be used as a context manager to create, hold and display a figure:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 2', width=500):
>>>     arlpy.plot.plot([0,10], [0,10], color='blue', legend='A')
>>>     arlpy.plot.plot([10,0], [0,10], marker='o', color='green', legend='B')

It can even be used as a context manager to work with Bokeh functions directly:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 3', width=500) as f:
>>>     f.line([0,10], [0,10], line_color='blue')
>>>     f.square([3,7], [4,5], line_color='green', fill_color='yellow', size=10)
class aubellhop.plotutils.many_figures(figsize: Tuple[int, int | None] = None)[source]

Create a grid of many figures.

Parameters:

figsize (tuple of int, optional) – Default size of figure in grid as (width, height)

Examples

>>> import arlpy.plot
>>> with arlpy.plot.many_figures(figsize=(300,200)):
>>>     arlpy.plot.plot([0,10], [0,10])
>>>     arlpy.plot.plot([0,10], [0,10])
>>>     arlpy.plot.next_row()
>>>     arlpy.plot.next_column()
>>>     arlpy.plot.plot([0,10], [0,10])
aubellhop.plotutils.next_row() → None[source]

Move to the next row in a grid of many figures.

aubellhop.plotutils.next_column() → None[source]

Move to the next column in a grid of many figures.

aubellhop.plotutils.gcf() → Any[source]

Get the current figure.

Returns:

handle to the current figure

aubellhop.plotutils.plot(x: Any, y: Any = None, fs: float | None = None, maxpts: int = 10000, pooling: str | None = None, color: str | None = None, style: str = 'solid', thickness: int = 1, marker: str | None = None, filled: bool = False, size: int = 6, mskip: int = 0, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: Tuple[float, float | None] = None, ylim: Tuple[float, float | None] = None, xtype: str = 'auto', ytype: str = 'auto', width: int | None = None, height: int | None = None, legend: str | None = None, interactive: bool | None = None, hold: bool = False) → None[source]

Plot a line graph or time series.

Parameters:

  • x – x data or time series data (if y is None)

  • y – y data or None (if time series)

  • fs – sampling rate for time series data

  • maxpts – maximum number of points to plot (downsampled if more points provided)

  • pooling – pooling for downsampling (None, ‘max’, ‘min’, ‘mean’, ‘median’)

  • color –

    line color (see Bokeh colors)

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’, None)

  • thickness – line width in pixels

  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)

  • filled – filled markers or outlined ones

  • size – marker size

  • mskip – number of points to skip marking (to avoid too many markers)

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width – figure width in pixels

  • height – figure height in pixels

  • legend – legend text

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.plot([0,10], [1,-1], color='blue', marker='o', filled=True, legend='A', hold=True)
>>> arlpy.plot.plot(np.random.normal(size=1000), fs=100, color='green', legend='B')
aubellhop.plotutils.scatter(x: Any, y: Any, marker: str = '.', filled: bool = False, size: int = 6, color: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: Tuple[float, float | None] = None, ylim: Tuple[float, float | None] = None, xtype: str = 'auto', ytype: str = 'auto', width: int | None = None, height: int | None = None, legend: str | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot a scatter plot.

Parameters:

  • x – x data

  • y – y data

  • color – marker color (see Bokeh colors)

  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)

  • filled – filled markers or outlined ones

  • size – marker size

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width – figure width in pixels

  • height – figure height in pixels

  • legend – legend text

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.scatter(np.random.normal(size=100), np.random.normal(size=100), color='blue', marker='o')
aubellhop.plotutils.image(img: Any, x: Any | None = None, y: Any | None = None, colormap: str = 'Plasma256', clim: Tuple[float, float | None] = None, clabel: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: Tuple[float, float | None] = None, ylim: Tuple[float, float | None] = None, xtype: str = 'auto', ytype: str = 'auto', width: int | None = None, height: int | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot a heatmap of 2D scalar data.

Parameters:

  • img – 2D image data

  • x – x-axis range for image data (min, max)

  • y – y-axis range for image data (min, max)

  • colormap – named color palette or Bokeh ColorMapper (see Bokeh palettes)

  • clim – color axis limits (min, max)

  • clabel – color axis label

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width – figure width in pixels

  • height – figure height in pixels

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.image(np.random.normal(size=(100,100)), colormap='Inferno256')
aubellhop.plotutils.vlines(x: Any, color: str = 'gray', style: str = 'dashed', thickness: int = 1, hold: bool = False) → None[source]

Draw vertical lines on a plot.

Parameters:

  • x – x location of lines

  • color – line color (see Bokeh colors)

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)

  • thickness – line width in pixels

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.vlines([7, 12])
aubellhop.plotutils.hlines(y: Any, color: str = 'gray', style: str = 'dashed', thickness: int = 1, hold: bool = False) → None[source]

Draw horizontal lines on a plot.

Parameters:

  • y – y location of lines

  • color – line color (see Bokeh colors)

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)

  • thickness – line width in pixels

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.hlines(3, color='red', style='dotted')
aubellhop.plotutils.text(x: float, y: float, s: str, color: str = 'gray', size: str = '8pt', hold: bool = False) → None[source]

Add text annotation to a plot.

Parameters:

  • x – x location of left of text

  • y – y location of bottom of text

  • s – text to add

  • color – text color (see Bokeh colors)

  • size – text size (e.g. ‘12pt’, ‘3em’)

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.text(7, 3, 'demo', color='orange')
aubellhop.plotutils.box(left: float | None = None, right: float | None = None, top: float | None = None, bottom: float | None = None, color: str = 'yellow', alpha: float = 0.1, hold: bool = False) → None[source]

Add a highlight box to a plot.

Parameters:

  • left – x location of left of box

  • right – x location of right of box

  • top – y location of top of box

  • bottom – y location of bottom of box

  • color – text color (see Bokeh colors)

  • alpha – transparency (0-1)

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.box(left=5, right=10, top=8)
aubellhop.plotutils.color(n: int) → str[source]

Get a numbered color to cycle over a set of colors.

>>> import arlpy.plot
>>> arlpy.plot.color(0)
'blue'
>>> arlpy.plot.color(1)
'red'
>>> arlpy.plot.plot([0, 20], [0, 10], color=arlpy.plot.color(3))
aubellhop.plotutils.set_colors(c: List[str]) → None[source]

Provide a list of named colors to cycle over.

>>> import arlpy.plot
>>> arlpy.plot.set_colors(['red', 'blue', 'green', 'black'])
>>> arlpy.plot.color(2)
'green'
aubellhop.plotutils.specgram(x: Any, fs: float = 2, nfft: int | None = None, noverlap: int | None = None, colormap: str = 'Plasma256', clim: Tuple[float, float | None] = None, clabel: str = 'dB', title: str | None = None, xlabel: str = 'Time (s)', ylabel: str = 'Frequency (Hz)', xlim: Tuple[float, float | None] = None, ylim: Tuple[float, float | None] = None, width: int | None = None, height: int | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot spectrogram of a given time series signal.

Parameters:

  • x – time series signal

  • fs – sampling rate

  • nfft – FFT size (see scipy.signal.spectrogram)

  • noverlap – overlap size (see scipy.signal.spectrogram)

  • colormap – named color palette or Bokeh ColorMapper (see Bokeh palettes)

  • clim – color axis limits (min, max), or dynamic range with respect to maximum

  • clabel – color axis label

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • width – figure width in pixels

  • height – figure height in pixels

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.specgram(np.random.normal(size=(10000)), fs=10000, clim=30)
aubellhop.plotutils.psd(x: Any, fs: float = 2, nfft: int = 512, noverlap: int | None = None, window: str = 'hann', color: str | None = None, style: str = 'solid', thickness: int = 1, marker: str | None = None, filled: bool = False, size: int = 6, title: str | None = None, xlabel: str = 'Frequency (Hz)', ylabel: str = 'Power spectral density (dB/Hz)', xlim: Tuple[float, float | None] = None, ylim: Tuple[float, float | None] = None, width: int | None = None, height: int | None = None, legend: str | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot power spectral density of a given time series signal.

Parameters:

  • x – time series signal

  • fs – sampling rate

  • nfft – segment size (see scipy.signal.welch)

  • noverlap – overlap size (see scipy.signal.welch)

  • window – window to use (see scipy.signal.welch)

  • color – line color (see Bokeh colors)

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)

  • thickness – line width in pixels

  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)

  • filled – filled markers or outlined ones

  • size – marker size

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • width – figure width in pixels

  • height – figure height in pixels

  • legend – legend text

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.psd(np.random.normal(size=(10000)), fs=10000)
aubellhop.plotutils.iqplot(data: Any, marker: str = '.', color: str | None = None, labels: Any | None = None, filled: bool = False, size: int | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: List[float] = [-2, 2], ylim: List[float] = [-2, 2], width: int | None = None, height: int | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot signal points.

Parameters:

  • data – complex baseband signal points

  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)

  • color – marker/text color (see Bokeh colors)

  • labels – label for each signal point, or True to auto-generate labels

  • filled – filled markers or outlined ones

  • size – marker/text size (e.g. 5, ‘8pt’)

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • width – figure width in pixels

  • height – figure height in pixels

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy
>>> import arlpy.plot
>>> arlpy.plot.iqplot(arlpy.comms.psk(8))
>>> arlpy.plot.iqplot(arlpy.comms.qam(16), color='red', marker='x')
>>> arlpy.plot.iqplot(arlpy.comms.psk(4), labels=['00', '01', '11', '10'])
aubellhop.plotutils.freqz(b: Any, a: Any = 1, fs: float = 2.0, worN: int | None = None, whole: bool = False, degrees: bool = True, style: str = 'solid', thickness: int = 1, title: str | None = None, xlabel: str = 'Frequency (Hz)', xlim: Tuple[float, float | None] = None, ylim: Tuple[float, float | None] = None, width: int | None = None, height: int | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot frequency response of a filter.

This is a convenience function to plot frequency response, and internally uses scipy.signal.freqz() to estimate the response. For further details, see the documentation for scipy.signal.freqz().

Parameters:

  • b – numerator of a linear filter

  • a – denominator of a linear filter

  • fs – sampling rate in Hz (optional, normalized frequency if not specified)

  • worN – see scipy.signal.freqz()

  • whole – see scipy.signal.freqz()

  • degrees – True to display phase in degrees, False for radians

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)

  • thickness – line width in pixels

  • title – figure title

  • xlabel – x-axis label

  • ylabel1 – y-axis label for magnitude

  • ylabel2 – y-axis label for phase

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • width – figure width in pixels

  • height – figure height in pixels

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy
>>> arlpy.plot.freqz([1,1,1,1,1], fs=120000);

Plotting functions (matplotlib)

Plotting functions using Matplotlib for aubellhop.

class aubellhop.pyplot.Any(*args, **kwargs)[source]

Special type indicating an unconstrained type.

  • Any is compatible with every type.

  • Any assumed to have all methods.

  • All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class aubellhop.pyplot.BHStrings(*values)[source]

String definitions to avoid hard-coding magic strings in the source code

This helps prevent typos and permits autocomplete (if your editor is smart enough).

default = 'default'
none = 'none'
two_d = '2D'
two_half_d = '2.5D'
three_d = '3D'
linear = 'linear'
spline = 'spline'
pchip = 'pchip'
nlinear = 'nlinear'
quadrilateral = 'quadrilateral'
hexahedral = 'hexahedral'
curvilinear = 'curvilinear'
vacuum = 'vacuum'
acousto_elastic = 'acousto-elastic'
rigid = 'rigid'
grain = 'grain'
from_file = 'from-file'
flat = 'flat'
line = 'line'
point = 'point'
cartesian = 'cartesian'
ray = 'ray'
hat_cartesian = 'hat-cartesian'
hat_ray = 'hat-ray'
gaussian_simple = 'gaussian-simple'
gaussian_cartesian = 'gaussian-cartesian'
gaussian_ray = 'gaussian-ray'
omnidirectional = 'omnidirectional'
single_beam = 'single beam'
rectilinear = 'rectilinear'
irregular = 'irregular'
thorp = 'thorp'
francois_garrison = 'francois-garrison'
biological = 'biological'
nepers_per_meter = 'nepers per meter'
frequency_dependent = 'frequency dependent'
db_per_meter = 'dB per meter'
db_per_wavelength = 'dB per wavelength'
quality_factor = 'quality factor'
loss_parameter = 'loss parameter'
rays = 'rays'
eigenrays = 'eigenrays'
arrivals = 'arrivals'
arrivals_b = 'arrivals-binary'
coherent = 'coherent'
incoherent = 'incoherent'
semicoherent = 'semicoherent'
class aubellhop.pyplot.Environment(name: str = 'bellhop/python default', _from_file: str | None = None, dimension: str = BHStrings.two_d, _dimension: int = 2, frequency: float = 25000.0, _num_media: int = 1, soundspeed: float | Any = 1500.0, soundspeed_interp: str = BHStrings.linear, _mesh_npts: int = 0, _depth_sigma: float = 0.0, _depth_max: float | None = None, _range_max: float | None = None, _bathymetry: str = BHStrings.flat, _altimetry: str = BHStrings.flat, _sbp_file: str = BHStrings.default, bottom_depth: float | Any = 25.0, bottom_interp: str = BHStrings.linear, _bottom_depth: float | None = None, bottom_soundspeed: float = 1500.0, _bottom_soundspeed_shear: float = 0.0, bottom_density: float = 1000.0, bottom_attenuation: float | None = None, _bottom_attenuation_shear: float | None = None, bottom_roughness: float = 0.0, bottom_beta: float | None = None, bottom_transition_freq: float | None = None, bottom_boundary_condition: str = BHStrings.acousto_elastic, bottom_reflection_coefficient: Any | None = None, bottom_grain_size: float | None = None, surface_depth: Any | None = None, surface_interp: str = BHStrings.linear, surface_boundary_condition: str = BHStrings.vacuum, surface_reflection_coefficient: Any | None = None, surface_soundspeed: float = 1500.0, _surface_soundspeed_shear: float = 0.0, surface_density: float = 1000.0, surface_attenuation: float | None = None, _surface_attenuation_shear: float | None = None, _surface_min: float | None = None, surface_min: float | None = None, source_type: str = BHStrings.default, source_range: float | Any = 0.0, source_cross_range: float | Any = 0.0, source_depth: float | Any = 5.0, source_ndepth: int | None = None, source_nrange: int | None = None, source_ncrossrange: int | None = None, source_directionality: Any | None = None, _source_num: int = 0, receiver_depth: float | Any = 10.0, receiver_range: float | Any = 1000.0, receiver_bearing: float | Any = 0.0, receiver_ndepth: int | None = None, receiver_nrange: int | None = None, receiver_nbearing: int | None = None, _receiver_num: int = 0, beam_type: str = BHStrings.default, beam_angle_min: float | None = None, beam_angle_max: float | None = None, beam_bearing_min: float | None = None, beam_bearing_max: float | None = None, beam_num: int = 0, beam_bearing_num: int = 0, single_beam_index: int | None = None, _single_beam: str = BHStrings.default, beam_width_type: str | None = None, beam_reflection_curvature_change: str | None = None, beam_reflection_shift: str | None = None, beam_epsilon_multipler: float | None = None, beam_range_loop: float | None = None, beam_images_num: int | None = None, beam_window: int | None = None, beam_component: str | None = None, simulation_depth: float | None = None, simulation_range: float | None = None, simulation_cross_range: float | None = None, simulation_depth_scale: float | None = None, simulation_range_scale: float | None = None, simulation_cross_range_scale: float | None = None, simulation_cross_range_min: float | None = None, step_size: float | None = 0.0, grid_type: str = BHStrings.default, task: str | None = None, interference_mode: str | None = None, volume_attenuation: str = BHStrings.none, attenuation_units: str = BHStrings.frequency_dependent, biological_layer_parameters: Any | None = None, _fg_salinity: float | None = None, _fg_temperature: float | None = None, _fg_pH: float | None = None, _fg_depth: float | None = None, comment_pad: int = 50)[source]

Dataclass for underwater acoustic environment configuration.

This class provides automatic validation of environment parameters, eliminating the need for manual checking of option validity.

These entries are either intended to be set or edited by the user, or with _ prefix are internal state read from a .env file or inferred by other data. Some others are ignored.

Parameters:

**kv (dict) – Keyword arguments for environment configuration.

Returns:

env – A new underwater environment dictionary.

Return type:

dict

Raises:

ValueError – If any parameter value is invalid according to BELLHOP constraints.

Example

To see all the parameters available and their default values:

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> print(env)

The environment parameters may be changed by passing keyword arguments or modified later using dictionary notation:

>>> import aubellhop as bh
>>> env = bh.Environment(bottom_depth=40, soundspeed=1540)
>>> print(env)
>>> env.bottom_depth = 25
>>> env.bottom_soundspeed = 1800
>>> print(env)

The default environment has a constant sound speed. A depth dependent sound speed profile be provided as a Nx2 array of (depth, sound speed):

>>> import aubellhop as bh
>>> env = bh.Environment(bottom_depth=20,
>>>         soundspeed=[[0,1540], [5,1535], [10,1535], [20,1530]])

A range-and-depth dependent sound speed profile can be provided as a Pandas frame:

>>> import aubellhop as bh
>>> import pandas as pd
>>> ssp2 = pd.DataFrame({
>>>       0: [1540, 1530, 1532, 1533],     # profile at 0 m range
>>>     100: [1540, 1535, 1530, 1533],     # profile at 100 m range
>>>     200: [1530, 1520, 1522, 1525] },   # profile at 200 m range
>>>     index=[0, 10, 20, 30])             # depths of the profile entries in m
>>> env = bh.Environment(bottom_depth=20, soundspeed=ssp2)

The default environment has a constant water depth. A range dependent bathymetry can be provided as a Nx2 array of (range, water depth):

>>> import aubellhop as bh
>>> env = bh.Environment(bottom_depth=[[0,20], [300,10], [500,18], [1000,15]])
name: str = 'bellhop/python default'
dimension: str = '2D'
frequency: float = 25000.0
soundspeed: float | Any = 1500.0
soundspeed_interp: str = 'linear'
bottom_depth: float | Any = 25.0
bottom_interp: str = 'linear'
bottom_soundspeed: float = 1500.0
bottom_density: float = 1000.0
bottom_attenuation: float | None = None
bottom_roughness: float = 0.0
bottom_beta: float | None = None
bottom_transition_freq: float | None = None
bottom_boundary_condition: str = 'acousto-elastic'
bottom_reflection_coefficient: Any | None = None
bottom_grain_size: float | None = None
surface_depth: Any | None = None
surface_interp: str = 'linear'
surface_boundary_condition: str = 'vacuum'
surface_reflection_coefficient: Any | None = None
surface_soundspeed: float = 1500.0
surface_density: float = 1000.0
surface_attenuation: float | None = None
surface_min: float | None = None
source_type: str = 'default'
source_range: float | Any = 0.0
source_cross_range: float | Any = 0.0
source_depth: float | Any = 5.0
source_ndepth: int | None = None
source_nrange: int | None = None
source_ncrossrange: int | None = None
source_directionality: Any | None = None
receiver_depth: float | Any = 10.0
receiver_range: float | Any = 1000.0
receiver_bearing: float | Any = 0.0
receiver_ndepth: int | None = None
receiver_nrange: int | None = None
receiver_nbearing: int | None = None
beam_type: str = 'default'
beam_angle_min: float | None = None
beam_angle_max: float | None = None
beam_bearing_min: float | None = None
beam_bearing_max: float | None = None
beam_num: int = 0
beam_bearing_num: int = 0
single_beam_index: int | None = None
beam_width_type: str | None = None
beam_reflection_curvature_change: str | None = None
beam_reflection_shift: str | None = None
beam_epsilon_multipler: float | None = None
beam_range_loop: float | None = None
beam_images_num: int | None = None
beam_window: int | None = None
beam_component: str | None = None
simulation_depth: float | None = None
simulation_range: float | None = None
simulation_cross_range: float | None = None
simulation_depth_scale: float | None = None
simulation_range_scale: float | None = None
simulation_cross_range_scale: float | None = None
simulation_cross_range_min: float | None = None
step_size: float | None = 0.0
grid_type: str = 'default'
task: str | None = None
interference_mode: str | None = None
volume_attenuation: str = 'none'
attenuation_units: str = 'frequency dependent'
biological_layer_parameters: Any | None = None
comment_pad: int = 50
classmethod from_file(fname: str) → Environment[source]

Create an Environment from an .env file.

classmethod from_dict(data: dict[str, Any]) → Environment[source]

Create Environment from dictionary.

Unlike Environment(**data), unknown fields are ignored (with a warning message).

to_file(fname: str, task: str | None = None) → str[source]

Write a complete .env file for specifying a Bellhop simulation.

This is the user-facing file writer. It infers the file basename and resolves the task from the environment unless overridden.

Parameters:

  • fname (str) – Filename or filename base for the .env file. If no extension is provided, .env is appended.

  • task (str, optional) – Task string which defines the computation to run (e.g. “rays”, “eigenrays”, “arrivals”, “coherent”, “incoherent”, “semicoherent”). If not provided, this is inferred from env.task or env.interference_mode.

Returns:

The filename base (no extension) of the written file.

Return type:

str

reset() → Self[source]

Delete values for all user-facing parameters.

defaults() → Self[source]

Applies default values if not already set.

to_dict() → dict[str, Any][source]

Return a dictionary representation of the environment.

copy() → Environment[source]

Return a shallow copy of the environment.

unwrap(*keys: str) → list[Environment][source]

Return a list of Environment copies expanded over the given keys.

If multiple keys are provided, all combinations are produced. Each unwrapped Environment gets a unique .name derived from the parent name and the expanded field values.

set_fg_attenuation(salinity: float, temperature: float, pH: float, depth: float) → Self[source]

Interface to set Francois-Garrison volume attenuation parameters.

check() → Self[source]

Finalise environment parameters and perform assertion checks.

aubellhop.pyplot.pyplot_env2d(env: Environment, surface_color: str = 'dodgerblue', bottom_color: str = 'peru', source_color: str = 'orangered', receiver_color: str = 'midnightblue', receiver_plot: bool | None = None, fill: bool | None = None, ax: Any | None = None, **kwargs: Any) → None[source]

Plots a visual representation of the environment with matplotlib.

Parameters:

  • env (dict) – Environment description

  • surface_color (str, default='dodgerblue') –

    Color of the surface (see Bokeh colors)

  • bottom_color (str, default='peru') –

    Color of the bottom (see Bokeh colors)

  • source_color (str, default='orangered') –

    Color of transmitters (see Bokeh colors)

  • receiver_color (str, default='midnightblue') –

    Color of receivers (see Bokeh colors)

  • receiver_plot (bool, optional) – True to plot all receivers, False to not plot any receivers, None to automatically decide

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

The surface, bottom, transmitters (marker: ‘*’) and receivers (marker: ‘o’) are plotted in the environment. If receiver_plot is set to None and there are more than 2000 receivers, they are not plotted.

Examples

>>> import aubellhop as bh
>>> env = bh.Environment(bottom_depth=[[0, 40], [100, 30], [500, 35], [700, 20], [1000,45]])
>>> bh.plot_env(env)
aubellhop.pyplot.pyplot_env3d(env: Environment, surface_color: str = 'dodgerblue', bottom_color: str = 'peru', source_color: str = 'orangered', receiver_color: str = 'midnightblue', receiver_plot: bool | None = None, ax: Any | None = None, **kwargs: Any) → None[source]

Plots a visual representation of the environment with matplotlib.

aubellhop.pyplot.pyplot_ssp(env: Environment, ax: Any | None = None, **kwargs: Any) → None[source]

Plots the sound speed profile with matplotlib.

Parameters:

  • env (Environment) – Environment description

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

If the sound speed profile is range-dependent, this function only plots the first profile.

Examples

>>> import aubellhop as bh
>>> env = bh.Environment(soundspeed=[[ 0, 1540], [10, 1530], [20, 1532], [25, 1533], [30, 1535]])
>>> bh.plot_ssp(env)
aubellhop.pyplot.pyplot_arrivals(arrivals: Any, dB: bool = False, color: str = 'blue', **kwargs: Any) → None[source]

Plots the arrival times and amplitudes with matplotlib.

Parameters:

  • arrivals (pandas.DataFrame) – Arrivals times (s) and coefficients

  • dB (bool, default=False) – True to plot in dB, False for linear scale

  • color (str, default='blue') –

    Line color (see Bokeh colors)

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> arrivals = bh.compute_arrivals(env)
>>> bh.plot_arrivals(arrivals)
aubellhop.pyplot.pyplot_rays(rays: Any, env: Environment | None = None, invert_colors: bool = False, ax: Any | None = None, **kwargs: Any) → matplotlib.axes.Axes[source]

Plots ray paths with matplotlib

Parameters:

  • rays (pandas.DataFrame) – Ray paths

  • env (Environment, optional) – Environment definition

  • invert_colors (bool, default=False) – False to use black for high intensity rays, True to use white

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

If environment definition is provided, it is overlayed over this plot using default parameters for bellhop.plot_env(). Without an environment file, no axis labels etc are provided, you are in charge of that.

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> rays = bh.compute_eigenrays(env)
>>> bh.plot_rays(rays, width=1000)
aubellhop.pyplot.pyplot_transmission_loss(tloss: Any, env: Environment | None = None, ax: Any | None = None, **kwargs: Any) → matplotlib.axes.Axes[source]

Plots transmission loss with matplotlib.

Parameters:

  • tloss (pandas.DataFrame) – Complex transmission loss

  • env (Environment, optional) – Environment definition

  • **kwargs – Other keyword arguments applicable for bellhop.plot.image() are also supported

Notes

If environment definition is provided, it is overlayed over this plot using default parameters for bellhop.plot_env().

Examples

>>> import aubellhop as bh
>>> import numpy as np
>>> env = bh.Environment(
        receiver_depth=np.arange(0, 25),
        receiver_range=np.arange(0, 1000),
        beam_angle_min=-45,
        beam_angle_max=45
    )
>>> tloss = bh.compute_transmission_loss(env)
>>> bh.plot_transmission_loss(tloss, width=1000)