Skip to content

Scenarios

neurotechdevkit.scenarios.Scenario(center_frequency=None, material_properties=None, material_masks=None, origin=None, sources=None, material_outline_upsample_factor=None, target=None, problem=None, grid=None)

Bases: abc.ABC

The base scenario.

All arguments are optional and can be set after initialization.

Parameters:

Name Type Description Default
center_frequency Optional[float]

The center frequency (in hertz) of the scenario. Defaults to None.

None
material_properties Optional[dict[str, Material]]

A map between material name and material properties. Defaults to None.

None
material_masks Optional[Mapping[str, npt.NDArray[np.bool_]]]

A map between material name and a boolean mask indicating which grid points are in that material. Defaults to None.

None
origin Optional[list[float]]

The location of the origin of the scenario (in meters). Defaults to None.

None
sources Optional[list[Source]]

The list of sources in the scenario. Defaults to None.

None
material_outline_upsample_factor Optional[int]

The factor by which to upsample the material outline when rendering the scenario. Defaults to None.

None
target Optional[Target]

The target in the scenario. Defaults to None.

None
problem Optional[Problem]

The problem definition for the scenario. Defaults to None.

None
grid Optional[Grid]

The grid for the scenario. Defaults to None.

None

center_frequency: float property writable

The center frequency (in hertz) of the scenario.

dt: float property

The spacing (in seconds) between consecutive timesteps of the simulation.

Only available once a simulation has been completed.

dx: float property

The spacing (in meters) between spatial grid points.

Spacing is the same in each spatial direction.

extent: npt.NDArray[np.float_] property

The extent of the spatial grid (in meters).

grid: Grid deletable property writable

The grid for the scenario.

layer_ids: Mapping[str, int] property

A map between material names and their layer id.

material_colors: dict[str, str] property

A map between material name and material render color.

Returns:

Type Description
dict[str, str]

dict[str, str]: keys are material names and values are the hex color

material_layer_ids: npt.NDArray[np.int_] property

Return the layer id for each grid point in the scenario.

material_layers: list[str] property

The list of material layers in the scenario.

materials: Mapping[str, Struct] property

Return a map between material name and material properties.

  • vp: the speed of sound (in m/s).
  • rho: the mass density (in kg/m³).
  • alpha: the absorption (in dB/cm).
  • render_color: the color used when rendering this material in the scenario layout plot.

problem: Problem deletable property writable

The problem definition for the scenario.

shape: npt.NDArray[np.int_] property

The shape of the spatial grid (in number of grid points).

t_max: float property

The maximum time (in seconds) of the simulation.

Only available once a simulation has been completed.

t_min: float property

The starting time (in seconds) of the simulation.

Only available once a simulation has been completed.

target: Target property writable

The target in the scenario.

target_center: npt.NDArray[np.float_] property

The coordinates of the center of the target region (in meters).

target_radius: float property

The radius of the target region (in meters).

compile_problem()

Compiles the problem for the scenario.

get_field_data(field)

Return the array of field values across the scenario for a particular field.

Common fields include:

  • vp: the speed of sound (in m/s)
  • rho: the density (in kg/m³)
  • alpha: absorption (in dB/cm)

Parameters:

Name Type Description Default
field str

the name of the field to return.

required

Returns:

Type Description
npt.NDArray[np.float_]

An array containing the field data.

simulate_steady_state(points_per_period=24, n_cycles_steady_state=10, time_to_steady_state=None, recording_time_undersampling=4, n_jobs=None)

Execute a steady-state simulation.

In this simulation, the sources will emit pressure waves with a continuous waveform until steady-state has been reached. The steady-state wave amplitude is found by taking the Fourier transform of the last n_cycles_steady_state cycles of data and taking the amplitude of the component at the center_frequency.

Warning

A poor choice of arguments to this function can lead to a failed simulation. Make sure you understand the impact of supplying parameter values other than the default if you chose to do so.

Parameters:

Name Type Description Default
points_per_period int

the number of points in time to simulate for each cycle of the wave.

24
n_cycles_steady_state int

the number of complete cycles to use when calculating the steady-state wave amplitudes.

10
time_to_steady_state float | None

the amount of time (in seconds) the simulation should run before measuring the steady-state amplitude. If the value is None, this time will automatically be set to the amount of time it would take to propagate from one corner to the opposite and back in the medium with the slowest speed of sound in the scenario.

None
recording_time_undersampling int

the undersampling factor to apply to the time axis when recording simulation results. One out of every this many consecutive time points will be recorded and all others will be dropped.

4
n_jobs int | None

the number of threads to be used for the computation. Use None to leverage Devito automatic tuning.

None

Returns:

Type Description
results.SteadyStateResult

An object containing the result of the steady-state simulation.

neurotechdevkit.scenarios.Scenario2D

Bases: Scenario

A 2D scenario.

get_target_mask()

Return the mask for the target region.

render_layout(show_sources=True, show_target=True, show_material_outlines=False)

Create a matplotlib figure showing the 2D scenario layout.

The grid can be turned on via: plt.grid(True)

Parameters:

Name Type Description Default
show_sources bool

whether or not to show the source transducer layer.

True
show_target bool

whether or not to show the target layer.

True
show_material_outlines bool

whether or not to display a thin white outline of the transition between different materials.

False

simulate_pulse(points_per_period=24, simulation_time=None, recording_time_undersampling=4, n_jobs=None)

Execute a pulsed simulation in 2D.

In this simulation, the sources will emit a pulse containing a few cycles of oscillation and then let the pulse propagate out to all edges of the scenario.

Warning

A poor choice of arguments to this function can lead to a failed simulation. Make sure you understand the impact of supplying parameter values other than the default if you chose to do so.

Parameters:

Name Type Description Default
points_per_period int

the number of points in time to simulate for each cycle of the wave.

24
simulation_time float | None

the amount of time (in seconds) the simulation should run. If the value is None, this time will automatically be set to the amount of time it would take to propagate from one corner to the opposite in the medium with the slowest speed of sound in the scenario.

None
recording_time_undersampling int

the undersampling factor to apply to the time axis when recording simulation results. One out of every this many consecutive time points will be recorded and all others will be dropped.

4
n_jobs int | None

the number of threads to be used for the computation. Use None to leverage Devito automatic tuning.

None

Returns:

Type Description
results.PulsedResult2D

An object containing the result of the 2D pulsed simulation.

neurotechdevkit.scenarios.Scenario3D(center_frequency=None, material_properties=None, material_masks=None, origin=None, sources=None, material_outline_upsample_factor=None, target=None, problem=None, grid=None, slice_axis=None, slice_position=None, viewer_config_3d=None)

Bases: Scenario

A 3D scenario.

All arguments are optional and can be set after initialization.

Parameters:

Name Type Description Default
center_frequency Optional[float]

The center frequency (in hertz) of the scenario. Defaults to None.

None
material_properties Optional[dict[str, Material]]

A map between material name and material properties. Defaults to None.

None
material_masks Optional[Mapping[str, npt.NDArray[np.bool_]]]

A map between material name and a boolean mask indicating which grid points are in that material. Defaults to None.

None
origin Optional[list[float]]

The location of the origin of the scenario (in meters). Defaults to None.

None
sources Optional[list[Source]]

The list of sources in the scenario. Defaults to None.

None
material_outline_upsample_factor Optional[int]

The factor by which to upsample the material outline when rendering the scenario. Defaults to None.

None
target Optional[Target]

The target in the scenario. Defaults to None.

None
problem Optional[Problem]

The problem definition for the scenario. Defaults to None.

None
grid Optional[Grid]

The grid for the scenario. Defaults to None.

None
slice_axis Optional[SliceAxis]

The axis along which to slice the 3D field to be recorded. If None, then the complete field will be recorded. Use 0 for X axis, 1 for Y axis and 2 for Z axis. Defaults to None.

None
slice_position Optional[float]

The position (in meters) along the slice axis at which the slice of the 3D field should be made. Defaults to None.

None
viewer_config_3d Optional[rendering.ViewerConfig3D]

The configuration to use when rendering the 3D scenario. Defaults to None.

None

get_target_mask()

Return the mask for the target region.

render_layout(show_sources=True, show_target=True, show_material_outlines=False)

Create a matplotlib figure showing a 2D slice of the scenario layout.

In order to visualize the 3D scenario in a 2D plot, a slice through the scenario needs to be specified via slice_axis and slice_position. Eg. to take a slice at z=0.01 m, use slice_axis=2 and slice_position=0.01.

The grid can be turned on via: plt.grid(True)

Parameters:

Name Type Description Default
show_sources bool

whether or not to show the source transducer layer.

True
show_target bool

whether or not to show the target layer.

True
show_material_outlines bool

whether or not to display a thin white outline of the transition between different materials.

False

render_layout_3d()

Render the scenario layout in 3D using napari.

This function requires the napari package to be installed.

Warning

Integration with napari is experimental, so do not be surprised if you encounter issues calling this function.

This will open up the napari interactive GUI in a separate window. The GUI contains many different controls for controlling the view of the data as well as the rendering of the layers. Among these, you can drag the scenario to view it from different angles, zoom in our out, and turn layers on or off.

See napari documentation for more information on the GUI: documentation

simulate_pulse(points_per_period=24, simulation_time=None, recording_time_undersampling=4, n_jobs=None, slice_axis=None, slice_position=None)

Execute a pulsed simulation in 3D.

In this simulation, the sources will emit a pulse containing a few cycles of oscillation and then let the pulse propagate out to all edges of the scenario.

Warning

A poor choice of arguments to this function can lead to a failed simulation. Make sure you understand the impact of supplying parameter values other than the default if you chose to do so.

Parameters:

Name Type Description Default
points_per_period int

the number of points in time to simulate for each cycle of the wave.

24
simulation_time float | None

the amount of time (in seconds) the simulation should run. If the value is None, this time will automatically be set to the amount of time it would take to propagate from one corner to the opposite in the medium with the slowest speed of sound in the scenario.

None
recording_time_undersampling int

the undersampling factor to apply to the time axis when recording simulation results. One out of every this many consecutive time points will be recorded and all others will be dropped.

4
n_jobs int | None

the number of threads to be used for the computation. Use None to leverage Devito automatic tuning.

None
slice_axis int | None

the axis along which to slice the 3D field to be recorded. If None, then the complete field will be recorded. Use 0 for X axis, 1 for Y axis and 2 for Z axis. Only valid if slice_position is not None.

None
slice_position float | None

the position (in meters) along the slice axis at which the slice of the 3D field should be made. Only valid if slice_axis is not None.

None

Returns:

Type Description
results.PulsedResult3D

An object containing the result of the 3D pulsed simulation.

neurotechdevkit.scenarios.built_in.Scenario0

Bases: Scenario2D

Scenario 0.

make_grid()

Make the grid for scenario 0.

neurotechdevkit.scenarios.built_in.Scenario1_2D

Bases: Scenario1, Scenario2D

A 2D implementation of scenario 1.

Scenario 1 is based on benchmark 4 of the following paper

Jean-Francois Aubry, Oscar Bates, Christian Boehm, et al., "Benchmark problems for transcranial ultrasound simulation: Intercomparison of compressional wave models", The Journal of the Acoustical Society of America 152, 1003 (2022); doi: 10.1121/10.0013426 https://asa.scitation.org/doi/pdf/10.1121/10.0013426

make_grid()

Make the grid for scenario 1 2D.

neurotechdevkit.scenarios.built_in.Scenario1_3D

Bases: Scenario1, Scenario3D

A 3D implementation of scenario 1.

Scenario 1 is based on benchmark 4 of the following paper

Jean-Francois Aubry, Oscar Bates, Christian Boehm, et al., "Benchmark problems for transcranial ultrasound simulation: Intercomparison of compressional wave models", The Journal of the Acoustical Society of America 152, 1003 (2022); doi: 10.1121/10.0013426 https://asa.scitation.org/doi/pdf/10.1121/10.0013426

make_grid()

Make the grid for scenario 1 3D.

neurotechdevkit.scenarios.built_in.Scenario2_2D

Bases: Scenario2D, Scenario2

A 2D implementation of scenario 2.

Scenario 2 is based on benchmark 8 of the following paper

Jean-Francois Aubry, Oscar Bates, Christian Boehm, et al., "Benchmark problems for transcranial ultrasound simulation: Intercomparison of compressional wave models", The Journal of the Acoustical Society of America 152, 1003 (2022); doi: 10.1121/10.0013426 https://asa.scitation.org/doi/pdf/10.1121/10.0013426

make_grid()

Make the grid for scenario 2 2D.

neurotechdevkit.scenarios.built_in.Scenario2_3D

Bases: Scenario2, Scenario3D

A 3D implementation of scenario 2.

Scenario 2 is based on benchmark 8 of the following paper

Jean-Francois Aubry, Oscar Bates, Christian Boehm, et al., "Benchmark problems for transcranial ultrasound simulation: Intercomparison of compressional wave models", The Journal of the Acoustical Society of America 152, 1003 (2022); doi: 10.1121/10.0013426 https://asa.scitation.org/doi/pdf/10.1121/10.0013426

make_grid()

Make the grid for scenario 2 3D.

neurotechdevkit.scenarios.Target dataclass

A class for containing metadata for a target.

Attributes:

Name Type Description
target_id str

the string id of the target.

center list[float]

the location of the center of the target (in meters).

radius float

the radius of the target (in meters).

description str

a text describing the target.