Compute submodule

Overview

┌─────────────────────────────────────────────────┐
│ import aubellhop as bh                          │
├─────────────────────────────────────────────────┤
│ bh.compute(env, task=["..."])                   │
│    → run computations using the auto model      │
│                                                 │
│ bh.compute(env, task=["..."], model=["..."])    │
│    → run computations using the specified model │
└─────────────────────────────────────────────────┘

Compute submodel

Computing wrappers for aubellhop.

These functions make use of the Models registry, selecting appropriate BellhopSimulator models (or loading explicitly request ones):

  • compute(env, …) — writes the environment to file and then executes an appropriate Bellhop model;

  • compute_from_file(model, filename) uses specified model with pre-existing environment file.

The compute() function allows calculation with multiple environments, tasks, and models, and returns the results in a dictionary of metadata and results.

Simpler once-off wrapper functions are also provided for convenience (compute_arrivals() etc.).

aubellhop.compute.compute_from_file(model: str, fname: str, debug: bool = False) → dict[str, Any][source]

Compute Bellhop model directly from existing .env file.

Parameters:

  • model (str) – Name of model to run that has been defined in the Models registry.

  • fname (str) – Filename of environment file (with or w/o extension).

  • debug (bool) – Whether to print diagnostics to the console.

Returns:

results – Dictionary of metadata and results.

Return type:

dict

Notes

The environment file is parsed simply to read the specified task; the bellhop executable is run on the original file “in place” in the filesystem. A copy of the parsed environment file is stored in the metadata.

aubellhop.compute.compute(env: Environment | list[Environment], model: Any | None = None, task: Any | None = None, debug: bool = False, fname_base: str | None = None, overwrite: bool = False) → dict[str, Any] | tuple[list[dict[str, Any]], DataFrame][source]

Compute Bellhop task(s) for given model(s) and environment(s).

Parameters:

  • env (dict or list of dict) – Environment definition (which includes the task specification)

  • model (str, optional) – Propagation model to use (None to auto-select)

  • task (str or list of str, optional) – Optional task or list of tasks (“arrivals”, etc.)

  • debug (bool, default=False) – Generate debug information for propagation model

  • fname_base (str, optional) – Base file name for Bellhop working files, default (None), creates a temporary file

  • overwrite (bool, default=False) – If True, remove any existing working/output files that share the same fname_base.

Returns:

  • dict – Single run result (and associated metadata) if only one computation is performed.

  • tuple of (list of dict, pandas.DataFrame) – List of results and an index DataFrame if multiple computations are performed.

Notes

If any of env, model, and/or task are lists then multiple runs are performed with a list of dictionary outputs returned. The ordering is based on loop iteration but might not be deterministic; use the index DataFrame to extract and filter the output logically.

Examples

Single task based on reading a complete .env file: >>> import aubellhop as bh >>> env = bh.Environment.from_file(”…”) >>> output = bh.compute(env) >>> assert output[‘task’] == “arrivals” >>> bh.plot_arrivals(output[‘results’])

Multiple tasks: >>> import aubellhop as bh >>> env = bh.Environment() >>> output, ind_df = bh.compute(env,task=[“arrivals”, “eigenrays”]) >>> bh.plot_arrivals(output[0][‘results’])

aubellhop.compute.compute_arrivals(env: Environment, model: Any | None = None, debug: bool = False, fname_base: str | None = None, overwrite: bool = False) → Any[source]

Compute arrivals between each transmitter and receiver.

Parameters:

  • env (dict) – Environment definition

  • model (str, optional) – Propagation model to use (None to auto-select)

  • debug (bool, default=False) – Generate debug information for propagation model

  • fname_base (str, optional) – Base file name for Bellhop working files, default (None), creates a temporary file

  • overwrite (bool, default=False) – If True, remove any existing working/output files that share the same fname_base.

Returns:

Arrival times and coefficients for all transmitter-receiver combinations

Return type:

pandas.DataFrame

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> arrivals = bh.compute_arrivals(env)
>>> bh.plot_arrivals(arrivals)
aubellhop.compute.compute_eigenrays(env: Environment, source_depth_ndx: int = 0, receiver_depth_ndx: int = 0, receiver_range_ndx: int = 0, model: Any | None = None, debug: bool = False, fname_base: str | None = None, overwrite: bool = False) → Any[source]

Compute eigenrays between a given transmitter and receiver.

Parameters:

  • env (dict) – Environment definition

  • source_depth_ndx (int, default=0) – Transmitter depth index

  • receiver_depth_ndx (int, default=0) – Receiver depth index

  • receiver_range_ndx (int, default=0) – Receiver range index

  • model (str, optional) – Propagation model to use (None to auto-select)

  • debug (bool, default=False) – Generate debug information for propagation model

  • fname_base (str, optional) – Base file name for Bellhop working files, default (None), creates a temporary file

  • overwrite (bool, default=False) – If True, remove any existing working/output files that share the same fname_base.

Returns:

Eigenrays paths

Return type:

pandas.DataFrame

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> rays = bh.compute_eigenrays(env)
>>> bh.plot_rays(rays, width=1000)
aubellhop.compute.compute_rays(env: Environment, source_depth_ndx: int = 0, model: Any | None = None, debug: bool = False, fname_base: str | None = None, overwrite: bool = False) → Any[source]

Compute rays from a given transmitter.

Parameters:

  • env (dict) – Environment definition

  • source_depth_ndx (int, default=0) – Transmitter depth index

  • model (str, optional) – Propagation model to use (None to auto-select)

  • debug (bool, default=False) – Generate debug information for propagation model

  • fname_base (str, optional) – Base file name for Bellhop working files, default (None), creates a temporary file

  • overwrite (bool, default=False) – If True, remove any existing working/output files that share the same fname_base.

Returns:

Ray paths

Return type:

pandas.DataFrame

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> rays = bh.compute_rays(env)
>>> bh.plot_rays(rays, width=1000)
aubellhop.compute.compute_transmission_loss(env: Environment, source_depth_ndx: int = 0, mode: str | None = None, model: Any | None = None, debug: bool = False, fname_base: str | None = None, overwrite: bool = False) → Any[source]

Compute transmission loss from a given transmitter to all receviers.

Parameters:

  • env (dict) – Environment definition

  • source_depth_ndx (int, default=0) – Transmitter depth index

  • mode (str, optional) – Coherent, incoherent or semicoherent

  • model (str, optional) – Propagation model to use (None to auto-select)

  • debug (bool, default=False) – Generate debug information for propagation model

  • fname_base (str, optional) – Base file name for Bellhop working files, default (None), creates a temporary file

  • overwrite (bool, default=False) – If True, remove any existing working/output files that share the same fname_base.

Returns:

Complex transmission loss at each receiver depth and range

Return type:

numpy.ndarray

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> tloss = bh.compute_transmission_loss(env, mode="incoherent")
>>> bh.plot_transmission_loss(tloss, width=1000)
aubellhop.compute.arrivals_to_impulse_response(arrivals: Any, fs: float, abs_time: bool = False) → Any[source]

Convert arrival times and coefficients to an impulse response.

Parameters:

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

  • fs (float) – Sampling rate (Hz)

  • abs_time (bool, default=False) – Absolute time (True) or relative time (False)

Returns:

Impulse response

Return type:

numpy.ndarray

Notes

If abs_time is set to True, the impulse response is placed such that the zero time corresponds to the time of transmission of signal.

Examples

>>> import aubellhop as bh
>>> env = bh.Environment()
>>> arrivals = bh.compute_arrivals(env)
>>> ir = bh.arrivals_to_impulse_response(arrivals, fs=192000)