acoustic_module

class AcousticAdapterBase(global_settings: Settings)[source]

Bases: SimulationModuleBase

This method is the entry method for running an acoustic forward model. It is invoked in the simpa.core.simulation.simulate method, but can also be called individually for the purposes of performing acoustic forward modeling only or in a different context.

The concrete will be chosen based on the:

Tags.ACOUSTIC_MODEL

tag in the settings dictionary.

Parameters:

  • global_settings (Settings) – The settings dictionary containing key-value pairs that determine the simulation. Here, it must contain the Tags.ACOUSTIC_MODEL tag and any tags that might be required by the specific acoustic model.

  • global_settings – The SIMPA settings dictionary

Raises:

AssertionError – an assertion error is raised if the Tags.ACOUSTIC_MODEL tag is not given or points to an unknown acoustic forward model.

abstract forward_model(detection_geometry) → ndarray[source]

This method performs the acoustic forward modeling given the initial pressure distribution and the acoustic tissue properties contained in the settings file. A deriving class needs to implement this method according to its model.

Returns:

time series pressure data

load_component_settings() → Settings[source]

Implements abstract method to serve acoustic settings as component settings

Returns:

Settings: acoustic component settings

run(digital_device_twin)[source]

Call this method to invoke the simulation process.

Parameters:

digital_device_twin –

Returns:

a numpy array containing the time series pressure data per detection element

class AcousticTestAdapter(global_settings: Settings)[source]

Bases: AcousticAdapterBase

Parameters:

global_settings (Settings) – The SIMPA settings dictionary

forward_model(device) → ndarray[source]

This method performs the acoustic forward modeling given the initial pressure distribution and the acoustic tissue properties contained in the settings file. A deriving class needs to implement this method according to its model.

Returns:

time series pressure data

class KWaveAdapter(global_settings: Settings)[source]

Bases: AcousticAdapterBase

The KwaveAdapter enables acoustic simulations to be run with the k-wave MATLAB toolbox. k-Wave is a free toolbox (http://www.k-wave.org/) developed by Bradley Treeby and Ben Cox (University College London) and Jiri Jaros (Brno University of Technology).

In order to use this toolbox, MATLAB needs to be installed on your system and the path to the MATLAB binary needs to be specified in the settings dictionary.

In order to use the toolbox from with SIMPA, a number of parameters have to be specified in the settings dictionary:

The initial pressure distribution:
    Tags.OPTICAL_MODEL_INITIAL_PRESSURE
Acoustic tissue properties:
    Tags.PROPERTY_SPEED_OF_SOUND
    Tags.PROPERTY_DENSITY
    Tags.PROPERTY_ALPHA_COEFF
The digital twin of the imaging device:
    Tags.DIGITAL_DEVICE
Other parameters:
    Tags.PERFORM_UPSAMPLING
    Tags.SPACING_MM
    Tags.UPSCALE_FACTOR
    Tags.PROPERTY_ALPHA_POWER
    Tags.GPU
    Tags.PMLInside
    Tags.PMLAlpha
    Tags.PlotPML
    Tags.RECORDMOVIE
    Tags.MOVIENAME
    Tags.ACOUSTIC_LOG_SCALE
    Tags.SENSOR_DIRECTIVITY_PATTERN

Many of these will be set automatically by SIMPA, but you may use the simpa.utils.settings_generator convenience methods to generate settings files that contain sensible defaults for these parameters.

Please also refer to the simpa_examples scripts to see how the settings file can be parametrized successfully.

Parameters:

global_settings (Settings) – The SIMPA settings dictionary

forward_model(detection_geometry: DetectionGeometryBase) → ndarray[source]

Runs the acoustic forward model and performs reading parameters and values from an hdf5 file before calling the actual algorithm and saves the updated settings afterwards.

Parameters:

detection_geometry –

Returns:

simulated time series data (numpy array)

k_wave_acoustic_forward_model(detection_geometry: DetectionGeometryBase, speed_of_sound: float, density: float, alpha_coeff: float, initial_pressure: ndarray, optical_path: str = 'temporary') → tuple[source]

Runs the acoustic forward model with the given parameters speed_of_sound (float), density (float), alpha_coeff (float) for the initial_pressure distribution (numpy array) and a given detection geometry. Uses the given optical_path (str) or if none is given a temporary one for saving temporary files. Note, that in order to work properly, this function assumes that several settings mentioned above are set. This can either be done by reading it from a settings file (e.g. when being called from forward_model) or by parsing all settings individually as in the convenience function (perform_k_wave_acoustic_forward_simulation).

Parameters:

  • detection_geometry –

  • speed_of_sound –

  • density –

  • alpha_coeff –

  • initial_pressure –

  • optical_path –

Returns:

time_series_data (numpy array): simulated time series data, global_settings (Settings): updated global settings with new entries from the simulation

perform_k_wave_acoustic_forward_simulation(initial_pressure: array, detection_geometry: DetectionGeometryBase, speed_of_sound: float = 1540.0, density: float = 1000.0, alpha_coeff: float = 0.02, acoustic_settings: Optional[Settings] = None, alpha_power: float = 0.0, sensor_record: str = 'p', pml_inside: bool = False, pml_alpha: float = 1.5, plot_pml: bool = False, record_movie: bool = False, movie_name: str = 'visualization_log', acoustic_log_scale: bool = True, gpu: bool = True, spacing_mm: float = 0.5) → array[source]

Convenience function for performing a k-Wave acoustic forward simulation using a given detection geometry and initial pressure distribution (numpy array) with the following parameters speed_of_sound (float), density (float), alpha_coeff (float) as well as acoustic_settings (Settings). The acoustic settings may be parsed individually, however, they will be overwritten if they are also set in the acoustic_settings.

Parameters:

  • initial_pressure –

  • detection_geometry –

  • speed_of_sound –

  • density –

  • alpha_coeff –

  • acoustic_settings –

  • alpha_power –

  • sensor_record –

  • pml_inside –

  • pml_alpha –

  • plot_pml –

  • record_movie –

  • movie_name –

  • acoustic_log_scale –

  • gpu –

  • spacing_mm –

Returns:

simulated time series data (numpy array)