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.

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)

center_frequency: float property writable

dt: float property

dx: float property

extent: npt.NDArray[np.float_] property

grid: Grid deletable property writable

layer_ids: Mapping[str, int] property

material_colors: dict[str, str] property

material_layer_ids: npt.NDArray[np.int_] property

material_layers: list[str] property

materials: Mapping[str, Struct] property

problem: Problem deletable property writable

shape: npt.NDArray[np.int_] property

t_max: float property

t_min: float property

target: Target property writable

target_center: npt.NDArray[np.float_] property

target_radius: float property

compile_problem()

get_field_data(field)

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

neurotechdevkit.scenarios.Scenario2D

get_target_mask()

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

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

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)

get_target_mask()

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

render_layout_3d()

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

neurotechdevkit.scenarios.built_in.Scenario0

make_grid()

neurotechdevkit.scenarios.built_in.Scenario1_2D

make_grid()

neurotechdevkit.scenarios.built_in.Scenario1_3D

make_grid()

neurotechdevkit.scenarios.built_in.Scenario2_2D

make_grid()

neurotechdevkit.scenarios.built_in.Scenario2_3D

make_grid()

neurotechdevkit.scenarios.Target dataclass

`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)`

`center_frequency: float` `property` `writable`

`dt: float` `property`

`dx: float` `property`

`extent: npt.NDArray[np.float_]` `property`

`grid: Grid` `deletable` `property` `writable`

`layer_ids: Mapping[str, int]` `property`

`material_colors: dict[str, str]` `property`

`material_layer_ids: npt.NDArray[np.int_]` `property`

`material_layers: list[str]` `property`

`materials: Mapping[str, Struct]` `property`

`problem: Problem` `deletable` `property` `writable`

`shape: npt.NDArray[np.int_]` `property`

`t_max: float` `property`

`t_min: float` `property`

`target: Target` `property` `writable`

`target_center: npt.NDArray[np.float_]` `property`

`target_radius: float` `property`

`compile_problem()`

`get_field_data(field)`

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

`neurotechdevkit.scenarios.Scenario2D`

`get_target_mask()`

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

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

`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)`

`get_target_mask()`

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

`render_layout_3d()`

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

`neurotechdevkit.scenarios.built_in.Scenario0`

`make_grid()`

`neurotechdevkit.scenarios.built_in.Scenario1_2D`

`make_grid()`

`neurotechdevkit.scenarios.built_in.Scenario1_3D`

`make_grid()`

`neurotechdevkit.scenarios.built_in.Scenario2_2D`

`make_grid()`

`neurotechdevkit.scenarios.built_in.Scenario2_3D`

`make_grid()`

`neurotechdevkit.scenarios.Target` `dataclass`