diff --git a/docs/api/scenarios.md b/docs/api/scenarios.md index 8a6f2d6f..5612c527 100644 --- a/docs/api/scenarios.md +++ b/docs/api/scenarios.md @@ -12,23 +12,23 @@ options: show_root_heading: true -::: neurotechdevkit.scenarios.built_in.Scenario0 +::: neurotechdevkit.scenarios.built_in.ScenarioSimple options: show_root_heading: true -::: neurotechdevkit.scenarios.built_in.Scenario1_2D +::: neurotechdevkit.scenarios.built_in.ScenarioFlatSkull_2D options: show_root_heading: true -::: neurotechdevkit.scenarios.built_in.Scenario1_3D +::: neurotechdevkit.scenarios.built_in.ScenarioFlatSkull_3D options: show_root_heading: true -::: neurotechdevkit.scenarios.built_in.Scenario2_2D +::: neurotechdevkit.scenarios.built_in.ScenarioRealisticSkull_2D options: show_root_heading: true -::: neurotechdevkit.scenarios.built_in.Scenario2_3D +::: neurotechdevkit.scenarios.built_in.ScenarioRealisticSkull_3D options: show_root_heading: true diff --git a/docs/examples/plot_adding_custom_source.py b/docs/examples/plot_adding_custom_source.py index f249a0f8..5c4b34a2 100644 --- a/docs/examples/plot_adding_custom_source.py +++ b/docs/examples/plot_adding_custom_source.py @@ -37,7 +37,7 @@ num_points=1000, ) -scenario = ndk.built_in.Scenario0() +scenario = ndk.built_in.ScenarioSimple() scenario.sources = [source] scenario.make_grid() scenario.compile_problem() diff --git a/docs/examples/plot_customized_center_frequency.py b/docs/examples/plot_customized_center_frequency.py index df3d9009..23d163ec 100644 --- a/docs/examples/plot_customized_center_frequency.py +++ b/docs/examples/plot_customized_center_frequency.py @@ -11,7 +11,7 @@ CENTER_FREQUENCY = 6e5 -scenario = ndk.scenarios.built_in.Scenario0() +scenario = ndk.scenarios.built_in.ScenarioSimple() # Customizing material properties scenario.material_properties = { diff --git a/docs/examples/plot_full_scenario.py b/docs/examples/plot_full_scenario.py index 53c648a1..32d9ad31 100644 --- a/docs/examples/plot_full_scenario.py +++ b/docs/examples/plot_full_scenario.py @@ -7,7 +7,7 @@ NDK and its examples are under constant development, more information and content will be added to this example soon! -The following code is a simplified implementation of NDK's Scenario 1. +The following code is a simplified implementation of NDK's ScenarioFlatSkull. """ # %% # Implementing a Scenario diff --git a/docs/examples/plot_metrics.py b/docs/examples/plot_metrics.py index 1666d794..726ed50f 100644 --- a/docs/examples/plot_metrics.py +++ b/docs/examples/plot_metrics.py @@ -14,7 +14,7 @@ # ## Rendering scenario import neurotechdevkit as ndk -scenario = ndk.built_in.Scenario0() +scenario = ndk.built_in.ScenarioSimple() scenario.make_grid() scenario.compile_problem() result = scenario.simulate_steady_state() diff --git a/docs/examples/plot_multiple_sources.py b/docs/examples/plot_multiple_sources.py index e1910fe1..562115c0 100644 --- a/docs/examples/plot_multiple_sources.py +++ b/docs/examples/plot_multiple_sources.py @@ -17,7 +17,7 @@ # %% import neurotechdevkit as ndk -scenario = ndk.built_in.Scenario0() +scenario = ndk.built_in.ScenarioSimple() s1 = ndk.sources.FocusedSource2D( position=[0.01, 0.0], diff --git a/docs/examples/plot_phased_array_source.py b/docs/examples/plot_phased_array_source.py index e66fee79..be3401f9 100644 --- a/docs/examples/plot_phased_array_source.py +++ b/docs/examples/plot_phased_array_source.py @@ -128,7 +128,7 @@ num_points=1000, ) -scenario = ndk.scenarios.built_in.Scenario1_2D() +scenario = ndk.scenarios.built_in.ScenarioFlatSkull_2D() scenario.sources = [source] scenario.make_grid() scenario.compile_problem() @@ -142,7 +142,7 @@ # delays are automatically computed when `focal_length` is defined. Let's explore how # the API looks like: -scenario = ndk.scenarios.built_in.Scenario1_2D() +scenario = ndk.scenarios.built_in.ScenarioFlatSkull_2D() phased_array = ndk.sources.PhasedArraySource2D( position=[0.0, 0.0], @@ -176,7 +176,7 @@ # In the example below we apply monotonically increasing delays to mimic a # counter-clockwise angle. -scenario = ndk.scenarios.built_in.Scenario1_2D() +scenario = ndk.scenarios.built_in.ScenarioFlatSkull_2D() phased_array = ndk.sources.PhasedArraySource2D( position=[0.0, 0.0], @@ -208,7 +208,7 @@ # # The rest of the API is identical for both 2D and 3D scenarios. -scenario_3d = ndk.scenarios.built_in.Scenario1_3D() +scenario_3d = ndk.scenarios.built_in.ScenarioFlatSkull_3D() phased_3d = ndk.sources.PhasedArraySource3D( position=[0.0, 0.0, 0.0], diff --git a/docs/examples/plot_pulsed_simulation.py b/docs/examples/plot_pulsed_simulation.py index 9427c941..a0d38205 100644 --- a/docs/examples/plot_pulsed_simulation.py +++ b/docs/examples/plot_pulsed_simulation.py @@ -9,7 +9,7 @@ # %% import neurotechdevkit as ndk -scenario = ndk.built_in.Scenario0() +scenario = ndk.built_in.ScenarioSimple() scenario.make_grid() scenario.compile_problem() result = scenario.simulate_pulse() diff --git a/docs/examples/plot_scenario2_predefined_target.py b/docs/examples/plot_scenario2_predefined_target.py deleted file mode 100644 index 3e189d45..00000000 --- a/docs/examples/plot_scenario2_predefined_target.py +++ /dev/null @@ -1,44 +0,0 @@ -# -*- coding: utf-8 -*- -""" - -Scenario 2 predefined target -==================================== - -!!! note - NDK and its examples are under constant development, more information - and content will be added to this example soon! - -This example demonstrates how to use one of the predefined targets of -scenario 2. -""" -# %% -# The list of supported targets is: -import neurotechdevkit as ndk - -scenario_2_2d_targets = ( - ndk.scenarios.built_in.Scenario2_2D.PREDEFINED_TARGET_OPTIONS.keys() -) -scenario_2_3d_targets = ( - ndk.scenarios.built_in.Scenario2_3D.PREDEFINED_TARGET_OPTIONS.keys() -) -print("2D predefined targets: \n\t", ", ".join(scenario_2_2d_targets), "\n\n") -print("3D predefined targets: \n\t", ", ".join(scenario_2_3d_targets), "\n\n") - -# %% -# Using one of the predefined targets is as simple as: -scenario = ndk.built_in.Scenario2_2D() -target_options = ndk.scenarios.built_in.Scenario2_2D.PREDEFINED_TARGET_OPTIONS -scenario.target = target_options["posterior-cingulate-cortex"] -scenario.make_grid() - -scenario.render_layout() - -# %% -# The same can be done for the 3D: -scenario_3d = ndk.built_in.Scenario2_3D() -target_options = ndk.scenarios.built_in.Scenario2_3D.PREDEFINED_TARGET_OPTIONS -scenario_3d.target = target_options["left-temporal-lobe"] -scenario_3d.make_grid() - -scenario_3d.render_layout() -# %% diff --git a/docs/examples/plot_scenario_predefined_target.py b/docs/examples/plot_scenario_predefined_target.py new file mode 100644 index 00000000..e1f6f6db --- /dev/null +++ b/docs/examples/plot_scenario_predefined_target.py @@ -0,0 +1,56 @@ +# -*- coding: utf-8 -*- +""" + +ScenarioRealisticSkull predefined target +==================================== + +!!! note + NDK and its examples are under constant development, more information + and content will be added to this example soon! + +This example demonstrates how to use one of the predefined targets of +ScenarioRealisticSkull. +""" +# %% +# The list of supported targets is: +import neurotechdevkit as ndk + +scenario_realistic_skull_2d_targets = ( + ndk.scenarios.built_in.ScenarioRealisticSkull_2D.PREDEFINED_TARGET_OPTIONS.keys() +) +scenario_realistic_skull_3d_targets = ( + ndk.scenarios.built_in.ScenarioRealisticSkull_3D.PREDEFINED_TARGET_OPTIONS.keys() +) +print( + "2D predefined targets: \n\t", + ", ".join(scenario_realistic_skull_2d_targets), + "\n\n", +) +print( + "3D predefined targets: \n\t", + ", ".join(scenario_realistic_skull_3d_targets), + "\n\n", +) + +# %% +# Using one of the predefined targets is as simple as: +scenario = ndk.built_in.ScenarioRealisticSkull_2D() +target_options = ( + ndk.scenarios.built_in.ScenarioRealisticSkull_2D.PREDEFINED_TARGET_OPTIONS +) +scenario.target = target_options["posterior-cingulate-cortex"] +scenario.make_grid() + +scenario.render_layout() + +# %% +# The same can be done for the 3D: +scenario_3d = ndk.built_in.ScenarioRealisticSkull_3D() +target_options = ( + ndk.scenarios.built_in.ScenarioRealisticSkull_3D.PREDEFINED_TARGET_OPTIONS +) +scenario_3d.target = target_options["left-temporal-lobe"] +scenario_3d.make_grid() + +scenario_3d.render_layout() +# %% diff --git a/docs/examples/plot_scenarios.py b/docs/examples/plot_scenarios.py index c9d95e45..90dd5335 100644 --- a/docs/examples/plot_scenarios.py +++ b/docs/examples/plot_scenarios.py @@ -20,18 +20,18 @@ def plot_scenario(chosen_scenario): # %% -# Simulating scenario: scenario 0 +# Simulating scenario: scenario-simple # =================================== -plot_scenario(ndk.scenarios.built_in.Scenario0) +plot_scenario(ndk.scenarios.built_in.ScenarioSimple) # %% -# Simulating scenario: scenario 1 2D +# Simulating scenario: scenario-flat-skull 2D # =================================== -plot_scenario(ndk.scenarios.built_in.Scenario1_2D) +plot_scenario(ndk.scenarios.built_in.ScenarioFlatSkull_2D) # %% -# Simulating scenario: scenario 2 2D +# Simulating scenario: scenario-realistic-skull 2D # =================================== -plot_scenario(ndk.scenarios.built_in.Scenario2_2D) +plot_scenario(ndk.scenarios.built_in.ScenarioRealisticSkull_2D) # %% diff --git a/docs/examples/plot_store_results.py b/docs/examples/plot_store_results.py index c898b67f..08fdb3e4 100644 --- a/docs/examples/plot_store_results.py +++ b/docs/examples/plot_store_results.py @@ -15,7 +15,7 @@ # Execute the following code in a computer with ndk installed import neurotechdevkit as ndk -scenario = ndk.built_in.Scenario0() +scenario = ndk.built_in.ScenarioSimple() scenario.make_grid() scenario.compile_problem() result = scenario.simulate_steady_state() diff --git a/docs/examples/plot_time_reverse.py b/docs/examples/plot_time_reverse.py index e76f8f0e..03e3566c 100644 --- a/docs/examples/plot_time_reverse.py +++ b/docs/examples/plot_time_reverse.py @@ -36,7 +36,7 @@ # %% # Helper function to make the scenario with a PhasedArraySource def make_scenario(element_delays=None): - true_scenario = ndk.scenarios.built_in.Scenario2_2D() + true_scenario = ndk.scenarios.built_in.ScenarioRealisticSkull_2D() # define a phased-array source default_source = true_scenario.sources[0] @@ -68,7 +68,7 @@ def make_scenario(element_delays=None): # The point source is visualized as a gray dot. # Reinitialize the scenario -reversed_scenario = ndk.scenarios.built_in.Scenario2_2D() +reversed_scenario = ndk.scenarios.built_in.ScenarioRealisticSkull_2D() # and reverse the source point_source = ndk.sources.PointSource2D( position=true_scenario.target.center, diff --git a/docs/examples/plot_ultrasound_imaging_multiplane.py b/docs/examples/plot_ultrasound_imaging_multiplane.py index 187b5d2a..501013fc 100644 --- a/docs/examples/plot_ultrasound_imaging_multiplane.py +++ b/docs/examples/plot_ultrasound_imaging_multiplane.py @@ -40,7 +40,7 @@ # Imaging modules from neurotechdevkit.imaging import beamform, demodulate, util from neurotechdevkit.results import PulsedResult2D, SteadyStateResult2D -from neurotechdevkit.scenarios.built_in import Scenario3 +from neurotechdevkit.scenarios.built_in import ScenarioUltrasoundPhantom from neurotechdevkit.sources import PhasedArraySource2D # %% @@ -93,9 +93,9 @@ # %% -def create_scenario(tilt_angle: float = 0.0) -> Scenario3: +def create_scenario(tilt_angle: float = 0.0) -> ScenarioUltrasoundPhantom: """Helper function to initialize scenario with different tilt angles.""" - scenario = Scenario3() + scenario = ScenarioUltrasoundPhantom() scenario.center_frequency = TONE_CENTER_FREQUENCY source_position = [0.01, 0.0] unit_direction = [1.0, 0.0] @@ -172,7 +172,7 @@ def create_scenario(tilt_angle: float = 0.0) -> Scenario3: # Helper functions: simulate long enough for ultrasound scattering reflection -def calc_simulation_time(scenario: Scenario3): +def calc_simulation_time(scenario: ScenarioUltrasoundPhantom): simulation_time = ndk.scenarios._time.select_simulation_time_for_pulsed( grid=scenario.grid, materials=scenario.materials, diff --git a/docs/examples/plot_ultrasound_imaging_scanline.py b/docs/examples/plot_ultrasound_imaging_scanline.py index 77f56fa5..d16dfe7b 100644 --- a/docs/examples/plot_ultrasound_imaging_scanline.py +++ b/docs/examples/plot_ultrasound_imaging_scanline.py @@ -41,7 +41,7 @@ # Imaging modules from neurotechdevkit.imaging import beamform, demodulate, util from neurotechdevkit.results import PulsedResult2D, SteadyStateResult2D -from neurotechdevkit.scenarios.built_in import Scenario3 +from neurotechdevkit.scenarios.built_in import ScenarioUltrasoundPhantom from neurotechdevkit.sources import PhasedArraySource2D # %% @@ -91,9 +91,9 @@ # %% -def create_scenario(tilt_angle: float = 0.0) -> Scenario3: +def create_scenario(tilt_angle: float = 0.0) -> ScenarioUltrasoundPhantom: """Helper function to initialize scenario with different tilt angles.""" - scenario = Scenario3() + scenario = ScenarioUltrasoundPhantom() scenario.center_frequency = TONE_CENTER_FREQUENCY source_position = [0.01, 0.0] unit_direction = [1.0, 0.0] @@ -171,7 +171,7 @@ def create_scenario(tilt_angle: float = 0.0) -> Scenario3: scenario = create_scenario() -def calc_simulation_time(scenario: Scenario3): +def calc_simulation_time(scenario: ScenarioUltrasoundPhantom): simulation_time = ndk.scenarios._time.select_simulation_time_for_pulsed( grid=scenario.grid, materials=scenario.materials, diff --git a/docs/index.md b/docs/index.md index f25dc219..34a457a6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,7 +49,7 @@ To install and run **neurotechdevkit** locally check the [installation](http://n ```python import neurotechdevkit as ndk -scenario = ndk.scenarios.built_in.Scenario0() +scenario = ndk.scenarios.built_in.ScenarioSimple() scenario.make_grid() scenario.compile_problem() result = scenario.simulate_steady_state() diff --git a/docs/usage/defining_sources.md b/docs/usage/defining_sources.md index 21e5aaf4..3f4249d7 100644 --- a/docs/usage/defining_sources.md +++ b/docs/usage/defining_sources.md @@ -5,7 +5,7 @@ Users can specify the parameters and placement of sources, and add them to their import neurotechdevkit as ndk import numpy as np -scenario = ndk.scenarios.built_in.Scenario2_2D() +scenario = ndk.scenarios.built_in.ScenarioRealisticSkull_2D() source = ndk.sources.FocusedSource2D( position=np.array([0.19, 0.07]), @@ -50,7 +50,7 @@ The 2D sources are for 2D scenarios and the 3D sources for 3D scenarios. The par import neurotechdevkit as ndk import numpy as np -scenario = ndk.scenarios.built_in.Scenario2_2D() +scenario = ndk.scenarios.built_in.ScenarioRealisticSkull_2D() source_position = np.array([0.19, 0.07]) source = ndk.sources.PlanarSource2D( diff --git a/docs/usage/gpu.md b/docs/usage/gpu.md index 22a19ba9..a5b33b9f 100644 --- a/docs/usage/gpu.md +++ b/docs/usage/gpu.md @@ -14,7 +14,7 @@ Now when running NDK simulations you should be able to see `platform=nvidiaX` in ```py import neurotechdevkit as ndk -scenario = ndk.scenarios.built_in.Scenario2_2D() +scenario = ndk.scenarios.built_in.ScenarioRealisticSkull_2D() scenario.make_grid() scenario.compile_problem() result = scenario.simulate_steady_state() diff --git a/docs/usage/loading_scenarios.md b/docs/usage/loading_scenarios.md index 32c842f7..0c36739a 100644 --- a/docs/usage/loading_scenarios.md +++ b/docs/usage/loading_scenarios.md @@ -9,17 +9,17 @@ The following is all that's needed to load a pre-defined scenario: ```py import neurotechdevkit as ndk -scenario = ndk.scenarios.built_in.Scenario2_2D() +scenario = ndk.scenarios.built_in.ScenarioRealisticSkull_2D() scenario.make_grid() ``` -The existing scenarios are: +The existing scenarios include: -- `SCENARIO_0` (2D) - a simple quickstart toy scenario that enables users to dive in and experiment with their first simulation immediately. -- `SCENARIO_1_3D` (3D) - a scenario containing a flat 3-layer bone covered by skin, with water above the skin and brain below the bone. This is based on benchmark 4 of [Jean-Francois Aubry, et al.](https://doi.org/10.1121/10.0013426). -- `SCENARIO_2_3D` (3D) - a scenario containing a full skull and brain mesh immersed in water. This is based on benchmark 8 of [Jean-Francois Aubry, et al.](https://doi.org/10.1121/10.0013426). -- `SCENARIO_1_2D` (2D) - a 2D version of scenario 1. -- `SCENARIO_2_2D` (2D) - a 2D version of scenario 2. +- `SCENARIO_SIMPLE` (2D) - a simple quick-start toy scenario that enables users to dive in and experiment with their first simulation immediately. +- `SCENARIO_FLAT_SKULL_3D` (3D) - a scenario containing a flat 3-layer bone covered by skin, with water above the skin and brain below the bone. This is based on benchmark 4 of [Jean-Francois Aubry, et al.](https://doi.org/10.1121/10.0013426). +- `SCENARIO_REALISTIC_SKULL_3D` (3D) - a scenario containing a full skull and brain mesh immersed in water. This is based on benchmark 8 of [Jean-Francois Aubry, et al.](https://doi.org/10.1121/10.0013426). +- `SCENARIO_FLAT_SKULL_2D` (2D) - a 2D version of `SCENARIO_FLAT_SKULL`. +- `SCENARIO_REALISTIC_SKULL_2D` (2D) - a 2D version of `SCENARIO_REALISTIC_SKULL`. All of these scenarios are immediately ready for visualization and simulation, with appropriate default parameters used where needed. diff --git a/docs/usage/running_simulation.md b/docs/usage/running_simulation.md index 9d3b33c6..c7a2455f 100644 --- a/docs/usage/running_simulation.md +++ b/docs/usage/running_simulation.md @@ -5,7 +5,7 @@ The following code shows how to run a simulation. ```py import neurotechdevkit as ndk -scenario = ndk.scenarios.built_in.Scenario2_2D() +scenario = ndk.scenarios.built_in.ScenarioRealisticSkull_2D() scenario.make_grid() scenario.compile_problem() result = scenario.simulate_steady_state() diff --git a/src/neurotechdevkit/scenarios/built_in/__init__.py b/src/neurotechdevkit/scenarios/built_in/__init__.py index f8c2b543..9d0d74f0 100644 --- a/src/neurotechdevkit/scenarios/built_in/__init__.py +++ b/src/neurotechdevkit/scenarios/built_in/__init__.py @@ -1,32 +1,32 @@ """Contain built-in scenarios for NDK.""" -from ._scenario_0 import Scenario0 -from ._scenario_1 import Scenario1_2D, Scenario1_3D -from ._scenario_2 import ( - Scenario2_2D, - Scenario2_2D_Benchmark7, - Scenario2_3D, - Scenario2_3D_Benchmark7, +from ._scenario_flat_skull import ScenarioFlatSkull_2D, ScenarioFlatSkull_3D +from ._scenario_realistic_skull import ( + ScenarioRealisticSkull_2D, + ScenarioRealisticSkull_3D, + ScenarioRealisticSkullCropped_2D, + ScenarioRealisticSkullCropped_3D, ) -from ._scenario_3 import Scenario3 +from ._scenario_simple import ScenarioSimple +from ._scenario_ultrasound_phantom import ScenarioUltrasoundPhantom __all__ = [ - "Scenario0", - "Scenario1_2D", - "Scenario1_3D", - "Scenario2_2D", - "Scenario2_3D", - "Scenario2_2D_Benchmark7", - "Scenario2_3D_Benchmark7", - "Scenario3", + "ScenarioSimple", + "ScenarioFlatSkull_2D", + "ScenarioFlatSkull_3D", + "ScenarioRealisticSkull_2D", + "ScenarioRealisticSkull_3D", + "ScenarioRealisticSkullCropped_2D", + "ScenarioRealisticSkullCropped_3D", + "ScenarioUltrasoundPhantom", ] BUILT_IN_SCENARIOS = { - "Scenario0": Scenario0, - "Scenario1_2D": Scenario1_2D, - "Scenario1_3D": Scenario1_3D, - "Scenario2_2D": Scenario2_2D, - "Scenario2_3D": Scenario2_3D, - "Scenario2_2D_Benchmark7": Scenario2_2D_Benchmark7, - "Scenario2_3D_Benchmark7": Scenario2_3D_Benchmark7, - "Scenario3": Scenario3, + "ScenarioSimple": ScenarioSimple, + "ScenarioFlatSkull_2D": ScenarioFlatSkull_2D, + "ScenarioFlatSkull_3D": ScenarioFlatSkull_3D, + "ScenarioRealisticSkull_2D": ScenarioRealisticSkull_2D, + "ScenarioRealisticSkull_3D": ScenarioRealisticSkull_3D, + "ScenarioRealisticSkullCropped_2D": ScenarioRealisticSkullCropped_2D, + "ScenarioRealisticSkullCropped_3D": ScenarioRealisticSkullCropped_3D, + "ScenarioUltrasoundPhantom": ScenarioUltrasoundPhantom, } diff --git a/src/neurotechdevkit/scenarios/built_in/_scenario_1.py b/src/neurotechdevkit/scenarios/built_in/_scenario_flat_skull.py similarity index 84% rename from src/neurotechdevkit/scenarios/built_in/_scenario_1.py rename to src/neurotechdevkit/scenarios/built_in/_scenario_flat_skull.py index 38ef1b13..b3b25076 100644 --- a/src/neurotechdevkit/scenarios/built_in/_scenario_1.py +++ b/src/neurotechdevkit/scenarios/built_in/_scenario_flat_skull.py @@ -12,16 +12,15 @@ from .._utils import SliceAxis, Target -class Scenario1(Scenario): - """Specific implementation detail for scenario 1. +class ScenarioFlatSkull(Scenario): + """Flat 3-layer bone covered by skin, with water above and brain below. - Scenario 1 is based on benchmark 4 of the following paper: + This scenario corresponds to 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 + 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 """ @@ -39,7 +38,7 @@ class Scenario1(Scenario): } def _make_material_masks(self) -> Mapping[str, npt.NDArray[np.bool_]]: - """Make the material masks for scenario 1.""" + """Make the scenario's material masks.""" material_layers = [ "water", "skin", @@ -48,7 +47,7 @@ def _make_material_masks(self) -> Mapping[str, npt.NDArray[np.bool_]]: "brain", ] material_masks = { - name: _create_scenario_1_mask(name, self.grid) for name in material_layers + name: _create_scenario_mask(name, self.grid) for name in material_layers } return material_masks @@ -56,7 +55,7 @@ def _make_grid( self, extent: Union[Tuple[float, float], Tuple[float, float, float]] ) -> Grid: """ - Make the grid for scenario 1. + Make the scenario's grid. Args: extent: the extent of the grid @@ -73,10 +72,10 @@ def _make_grid( return grid -class Scenario1_2D(Scenario1, Scenario2D): - """A 2D implementation of scenario 1. +class ScenarioFlatSkull_2D(ScenarioFlatSkull, Scenario2D): + """A 2D implementation of ScenarioFlatSkull. - Scenario 1 is based on benchmark 4 of the following paper: + ScenarioFlatSkull 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 @@ -100,16 +99,16 @@ class Scenario1_2D(Scenario1, Scenario2D): material_outline_upsample_factor = 8 def make_grid(self): - """Make the grid for scenario 1 2D.""" + """Make the scenario's 2D grid.""" extent = (0.12, 0.07) self.grid = self._make_grid(extent) self.material_masks = self._make_material_masks() -class Scenario1_3D(Scenario1, Scenario3D): - """A 3D implementation of scenario 1. +class ScenarioFlatSkull_3D(ScenarioFlatSkull, Scenario3D): + """A 3D implementation of ScenarioFlatSkull. - Scenario 1 is based on benchmark 4 of the following paper: + ScenarioFlatSkull 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 @@ -160,13 +159,13 @@ class Scenario1_3D(Scenario1, Scenario3D): material_outline_upsample_factor = 8 def make_grid(self): - """Make the grid for scenario 1 3D.""" + """Make the scenario's 3D grid.""" extent = (0.12, 0.07, 0.07) self.grid = self._make_grid(extent) self.material_masks = self._make_material_masks() -def _create_scenario_1_mask(material, grid): +def _create_scenario_mask(material, grid): # layers are defined by X position dx = grid.space.spacing[0] diff --git a/src/neurotechdevkit/scenarios/built_in/_scenario_2.py b/src/neurotechdevkit/scenarios/built_in/_scenario_realistic_skull.py similarity index 91% rename from src/neurotechdevkit/scenarios/built_in/_scenario_2.py rename to src/neurotechdevkit/scenarios/built_in/_scenario_realistic_skull.py index e880fa56..ad60bf07 100644 --- a/src/neurotechdevkit/scenarios/built_in/_scenario_2.py +++ b/src/neurotechdevkit/scenarios/built_in/_scenario_realistic_skull.py @@ -18,23 +18,23 @@ @enum.unique class BenchmarkSkullMaskFile(enum.Enum): - """Aliases for the skull mask filename for each Scenario2 benchmark.""" + """Aliases for the skull mask filename for each ScenarioRealisticSkull benchmark.""" BENCHMARK_7 = "skull_mask_bm7_dx_0.5mm.mat" BENCHMARK_8 = "skull_mask_bm8_dx_0.5mm.mat" class BenchmarkExtent(enum.Enum): - """Aliases for the extent for each Scenario2 benchmark.""" + """Aliases for the extent for each ScenarioRealisticSkull benchmark.""" BENCHMARK_7 = (0.120, 0.070, 0.070) # m BENCHMARK_8 = (0.225, 0.170, 0.190) # m -class Scenario2(Scenario): - """Specific implementation detail for scenario 2. +class ScenarioRealisticSkull(Scenario): + """A scenario containing a full skull and brain mesh immersed in water. - Scenario 2 is based on benchmark 8 of the following paper: + This scenario corresponds to 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 @@ -69,7 +69,7 @@ def _make_material_masks( mask_file_name: str = BenchmarkSkullMaskFile.BENCHMARK_8.value, convert_2d: bool = False, ) -> Mapping[str, npt.NDArray[np.bool_]]: - """Make the material masks for scenario 2.""" + """Make the scenario's material masks.""" material_layers = [ "water", "cortical_bone", @@ -77,7 +77,7 @@ def _make_material_masks( ] assert self.grid.space is not None, "Grid-space must be created first." material_masks = { - name: _create_scenario_2_mask( + name: _create_scenario_mask( name, output_shape=self.grid.space.shape, mask_file_name=mask_file_name, @@ -88,10 +88,10 @@ def _make_material_masks( return material_masks -class Scenario2_2D(Scenario2D, Scenario2): - """A 2D implementation of scenario 2. +class ScenarioRealisticSkull_2D(Scenario2D, ScenarioRealisticSkull): + """A 2D implementation of ScenarioRealisticSkull. - Scenario 2 is based on benchmark 8 of the following paper: + ScenarioRealisticSkull 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 @@ -160,17 +160,17 @@ class Scenario2_2D(Scenario2D, Scenario2): material_outline_upsample_factor = 4 def make_grid(self): - """Make the grid for scenario 2 2D.""" + """Make the scenario's 2D grid.""" self.grid = self._make_grid(BenchmarkExtent.BENCHMARK_8.value[:2]) self.material_masks = self._make_material_masks( mask_file_name=BenchmarkSkullMaskFile.BENCHMARK_8.value, convert_2d=True ) -class Scenario2_3D(Scenario2, Scenario3D): - """A 3D implementation of scenario 2. +class ScenarioRealisticSkull_3D(ScenarioRealisticSkull, Scenario3D): + """A 3D implementation of ScenarioRealisticSkull. - Scenario 2 is based on benchmark 8 of the following paper: + ScenarioRealisticSkull 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 @@ -282,15 +282,15 @@ class Scenario2_3D(Scenario2, Scenario3D): material_outline_upsample_factor = 4 def make_grid(self): - """Make the grid for scenario 2 3D.""" + """Make the scenario's 3D grid.""" self.grid = self._make_grid(BenchmarkExtent.BENCHMARK_8.value) self.material_masks = self._make_material_masks( mask_file_name=BenchmarkSkullMaskFile.BENCHMARK_8.value, convert_2d=False ) -class Scenario2_2D_Benchmark7(Scenario2_2D): - """An adaptation of scenario 2 2D that uses the benchmark 7 sub-extent. +class ScenarioRealisticSkullCropped_2D(ScenarioRealisticSkull_2D): + """An adaptation of ScenarioRealisticSkull 2D that uses the benchmark 7 sub-extent. From Aubry et al. (2022): > Benchmark 7... uses a subset of the skull mask and the @@ -309,8 +309,8 @@ def make_grid(self): ) -class Scenario2_3D_Benchmark7(Scenario2_3D): - """An adaptation of scenario 2 3D that uses the benchmark 7 sub-extent. +class ScenarioRealisticSkullCropped_3D(ScenarioRealisticSkull_3D): + """An adaptation of ScenarioRealisticSkull 3D that uses the benchmark 7 sub-extent. From Aubry et al. (2022): > Benchmark 7... uses a subset of the skull mask and the @@ -329,13 +329,13 @@ def make_grid(self): ) -def _create_scenario_2_mask( +def _create_scenario_mask( material: str, output_shape: Tuple[int], mask_file_name: str = BenchmarkSkullMaskFile.BENCHMARK_8.value, # m convert_2d: bool = False, ) -> npt.NDArray[np.bool_]: - """Create material mask for scenario 2. + """Create the scenario's material mask. Args: material: name of the material to create the mask for diff --git a/src/neurotechdevkit/scenarios/built_in/_scenario_0.py b/src/neurotechdevkit/scenarios/built_in/_scenario_simple.py similarity index 91% rename from src/neurotechdevkit/scenarios/built_in/_scenario_0.py rename to src/neurotechdevkit/scenarios/built_in/_scenario_simple.py index 8879ecf4..6b24cd9c 100644 --- a/src/neurotechdevkit/scenarios/built_in/_scenario_0.py +++ b/src/neurotechdevkit/scenarios/built_in/_scenario_simple.py @@ -10,8 +10,11 @@ from .._utils import Target, create_grid_circular_mask, create_grid_elliptical_mask -class Scenario0(Scenario2D): - """Scenario 0.""" +class ScenarioSimple(Scenario2D): + """A simple scenario to get started with your first simulation. + + Consists of a 2-D elliptical skull with a tumor in the brain. + """ center_frequency = 5e5 # Hz target = Target( @@ -41,7 +44,7 @@ class Scenario0(Scenario2D): } def _make_material_masks(self) -> Mapping[str, npt.NDArray[np.bool_]]: - """Make the material masks for scenario 0.""" + """Make the scenario's material masks.""" material_layers = [ "water", "cortical_bone", @@ -49,7 +52,7 @@ def _make_material_masks(self) -> Mapping[str, npt.NDArray[np.bool_]]: "tumor", ] material_masks = { - name: _create_scenario_0_mask( + name: _create_scenario_mask( name, self.grid, np.array(self.origin, dtype=float) ) for name in material_layers @@ -57,7 +60,7 @@ def _make_material_masks(self) -> Mapping[str, npt.NDArray[np.bool_]]: return material_masks def make_grid(self): - """Make the grid for scenario 0.""" + """Make the scenario grid.""" self.grid = Grid.make_grid( extent=(0.05, 0.04), # m speed_water=1500, # m/s @@ -67,7 +70,7 @@ def make_grid(self): self.material_masks = self._make_material_masks() -def _create_scenario_0_mask(material, grid, origin): +def _create_scenario_mask(material, grid, origin): if material == "water": outer_skull_mask = _create_skull_interface_mask(grid, origin) water_mask = ~outer_skull_mask diff --git a/src/neurotechdevkit/scenarios/built_in/_scenario_3.py b/src/neurotechdevkit/scenarios/built_in/_scenario_ultrasound_phantom.py similarity index 98% rename from src/neurotechdevkit/scenarios/built_in/_scenario_3.py rename to src/neurotechdevkit/scenarios/built_in/_scenario_ultrasound_phantom.py index b9daf34e..3c12fe3c 100644 --- a/src/neurotechdevkit/scenarios/built_in/_scenario_3.py +++ b/src/neurotechdevkit/scenarios/built_in/_scenario_ultrasound_phantom.py @@ -14,7 +14,7 @@ from .._utils import create_grid_circular_mask -class Scenario3(Scenario2D): +class ScenarioUltrasoundPhantom(Scenario2D): """Imaging Scenario: grainy phantoms in water.""" _PHANTOM_RADIUS = 0.01 # m @@ -55,7 +55,7 @@ class Scenario3(Scenario2D): material_outline_upsample_factor = 4 def make_grid(self): - """Make the grid for scenario 2 3D.""" + """Make the scenario's 3D grid.""" self.grid = Grid.make_grid( extent=self._extent, speed_water=1500, # m/s diff --git a/tests/neurotechdevkit/scenarios/test_builtin.py b/tests/neurotechdevkit/scenarios/test_builtin.py index 7b5e7979..66adc995 100644 --- a/tests/neurotechdevkit/scenarios/test_builtin.py +++ b/tests/neurotechdevkit/scenarios/test_builtin.py @@ -1,29 +1,29 @@ -"""Test built-in scenario 2.""" +"""Test built-in scenarios.""" import pytest from neurotechdevkit.scenarios.built_in import ( - Scenario0, - Scenario1_2D, - Scenario1_3D, - Scenario2_2D, - Scenario2_2D_Benchmark7, - Scenario2_3D, - Scenario2_3D_Benchmark7, - Scenario3, + ScenarioFlatSkull_2D, + ScenarioFlatSkull_3D, + ScenarioRealisticSkull_2D, + ScenarioRealisticSkull_3D, + ScenarioRealisticSkullCropped_2D, + ScenarioRealisticSkullCropped_3D, + ScenarioSimple, + ScenarioUltrasoundPhantom, ) @pytest.fixture( params=[ - Scenario0, - Scenario1_2D, - Scenario1_3D, - Scenario2_2D, - Scenario2_3D, - Scenario2_2D_Benchmark7, - Scenario2_3D_Benchmark7, - Scenario3, + ScenarioSimple, + ScenarioFlatSkull_2D, + ScenarioFlatSkull_3D, + ScenarioRealisticSkull_2D, + ScenarioRealisticSkull_3D, + ScenarioRealisticSkullCropped_2D, + ScenarioRealisticSkullCropped_3D, + ScenarioUltrasoundPhantom, ] ) def scenario_cls(request): diff --git a/tests/neurotechdevkit/scenarios/test_metrics.py b/tests/neurotechdevkit/scenarios/test_metrics.py index 88252c4b..b7e4b7c2 100644 --- a/tests/neurotechdevkit/scenarios/test_metrics.py +++ b/tests/neurotechdevkit/scenarios/test_metrics.py @@ -20,7 +20,7 @@ calculate_mechanical_index, ) from neurotechdevkit.results._results import SteadyStateResult2D -from neurotechdevkit.scenarios.built_in import Scenario1_2D +from neurotechdevkit.scenarios.built_in import ScenarioFlatSkull_2D GRID_SHAPE = (21, 31) CENTER_FREQUENCY = 1.5e6 @@ -340,7 +340,7 @@ def test_compare_metrics_to_aubry2022(): # Benchmark 4 corresponds to scenario 1 # The simulation resolution was slightly different, but # let's use the object to wrap the data anyway - scenario = Scenario1_2D() + scenario = ScenarioFlatSkull_2D() scenario.make_grid() scenario.compile_problem() result = SteadyStateResult2D( diff --git a/tests/neurotechdevkit/scenarios/test_results.py b/tests/neurotechdevkit/scenarios/test_results.py index 02cd1027..f4ca703f 100644 --- a/tests/neurotechdevkit/scenarios/test_results.py +++ b/tests/neurotechdevkit/scenarios/test_results.py @@ -108,7 +108,7 @@ def pulsed_data_2d(): @pytest.fixture def a_test_scenario_2d(): """A real 2D scenario that can be saved to disk and reloaded.""" - scenario = scenarios.built_in.Scenario1_2D() + scenario = scenarios.built_in.ScenarioFlatSkull_2D() original_sources = [source for source in scenario.sources] scenario.sources = [ sources.FocusedSource2D( @@ -129,7 +129,7 @@ def a_test_scenario_2d(): @pytest.fixture def a_test_scenario_3d(): """A real 3D scenario that can be saved to disk and reloaded.""" - scenario = scenarios.built_in.Scenario1_3D() + scenario = scenarios.built_in.ScenarioFlatSkull_3D() original_sources = [source for source in scenario.sources] scenario.sources = [ sources.FocusedSource3D(