Environment class

Overview

┌───────────────────────────────────────────────┐
│ import aubellhop as bh                        │
├───────────────────────────────────────────────┤
│ env = bh.Environment(...)                     │
│    → create new Environment instance          │
└───────────────────────────────────────────────┘

Environment class

Environment configuration for aubellhop.

This module provides dataclass-based environment configuration with automatic validation, replacing manual option checking with field validators.

class aubellhop.environment.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)

Bases: MutableMapping[str, Any]

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

dimension: str

frequency: float

soundspeed: float | Any

soundspeed_interp: str

bottom_depth: float | Any

bottom_interp: str

bottom_soundspeed: float

bottom_density: float

bottom_attenuation: float | None

bottom_roughness: float

bottom_beta: float | None

bottom_transition_freq: float | None

bottom_boundary_condition: str

bottom_reflection_coefficient: Any | None

bottom_grain_size: float | None

surface_depth: Any | None

surface_interp: str

surface_boundary_condition: str

surface_reflection_coefficient: Any | None

surface_soundspeed: float

surface_density: float

surface_attenuation: float | None

surface_min: float | None

source_type: str

source_range: float | Any

source_cross_range: float | Any

source_depth: float | Any

source_ndepth: int | None

source_nrange: int | None

source_ncrossrange: int | None

source_directionality: Any | None

receiver_depth: float | Any

receiver_range: float | Any

receiver_bearing: float | Any

receiver_ndepth: int | None

receiver_nrange: int | None

receiver_nbearing: int | None

beam_type: str

beam_angle_min: float | None

beam_angle_max: float | None

beam_bearing_min: float | None

beam_bearing_max: float | None

beam_num: int

beam_bearing_num: int

single_beam_index: int | None

beam_width_type: str | None

beam_reflection_curvature_change: str | None

beam_reflection_shift: str | None

beam_epsilon_multipler: float | None

beam_range_loop: float | None

beam_images_num: int | None

beam_window: int | None

beam_component: str | None

simulation_depth: float | None

simulation_range: float | None

simulation_cross_range: float | None

simulation_depth_scale: float | None

simulation_range_scale: float | None

simulation_cross_range_scale: float | None

simulation_cross_range_min: float | None

step_size: float | None

grid_type: str

task: str | None

interference_mode: str | None

volume_attenuation: str

attenuation_units: str

biological_layer_parameters: Any | None

comment_pad: int

classmethod from_file(fname: str) → Environment

Create an Environment from an .env file.

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

Create Environment from dictionary.

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

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

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

Delete values for all user-facing parameters.

defaults() → Self

Applies default values if not already set.

to_dict() → dict[str, Any]

Return a dictionary representation of the environment.

copy() → Environment

Return a shallow copy of the environment.

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

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

Interface to set Francois-Garrison volume attenuation parameters.

check() → Self

Finalise environment parameters and perform assertion checks.