diff --git a/README.md b/README.md index 6cf1db06..4dd5e9b3 100755 --- a/README.md +++ b/README.md @@ -199,6 +199,22 @@ once for checking if it works and then parse [--number 100] to run it at eg 100 Please see [benchmarking.md](docs/source/benchmarking.md) for a complete explanation. +# Understanding SIMPA + +**Tags** are identifiers in SIMPA used to categorize settings and components within simulations, making configurations +modular, readable, and manageable. Tags offer organizational, flexible, and reusable benefits by acting as keys in +configuration dictionaries. + +**Settings** in SIMPA control simulation behavior. They include: + +- **Global Settings**: Apply to the entire simulation, affecting overall properties and parameters. +- **Component Settings**: Specific to individual components, allowing for detailed customization and optimization of +each part of the simulation. + +Settings are defined in a hierarchical structure, where global settings are established first, followed by +component-specific settings. This approach ensures comprehensive and precise control over the simulation process. +For detailed information, users can refer to the [understanding SIMPA documentation](./docs/source/understanding_simpa.md). + # Troubleshooting In this section, known problems are listed with their solutions (if available): @@ -211,6 +227,11 @@ If you encounter an error similar to: The filename specified was either not found on the MATLAB path or it contains unsupported characters. Look up the solution in [this thread of the k-Wave forum](http://www.k-wave.org/forum/topic/error-reading-h5-files-when-using-binaries). + +## 2. KeyError: 'time_series_data' + +This is the error which will occur for ANY k-Wave problem. For the actual root of the problem, please either look above in +the terminal for the source of the bug or run the scripts in Matlab to find it manually. # Citation diff --git a/docs/source/index.rst b/docs/source/index.rst index 4539b02a..1472bfc4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,8 +20,9 @@ pipeline according to their specific use cases and tool requirements. :caption: SIMPA toolkit intro_link - contributing_link + understanding_link.md bench_link.md + contributing_link =================================== diff --git a/docs/source/simpa.core.device_digital_twins.detection_geometries.rst b/docs/source/simpa.core.device_digital_twins.detection_geometries.rst index 3eb9caa8..413d22fa 100644 --- a/docs/source/simpa.core.device_digital_twins.detection_geometries.rst +++ b/docs/source/simpa.core.device_digital_twins.detection_geometries.rst @@ -12,6 +12,12 @@ detection\_geometries :show-inheritance: +.. automodule:: simpa.core.device_digital_twins.detection_geometries.detection_geometry_base + :members: + :undoc-members: + :show-inheritance: + + .. automodule:: simpa.core.device_digital_twins.detection_geometries.linear_array :members: :undoc-members: diff --git a/docs/source/simpa.core.device_digital_twins.illumination_geometries.rst b/docs/source/simpa.core.device_digital_twins.illumination_geometries.rst index eb29ecbd..b398a489 100644 --- a/docs/source/simpa.core.device_digital_twins.illumination_geometries.rst +++ b/docs/source/simpa.core.device_digital_twins.illumination_geometries.rst @@ -18,6 +18,12 @@ illumination\_geometries :show-inheritance: +.. automodule:: simpa.core.device_digital_twins.illumination_geometries.illumination_geometry_base + :members: + :undoc-members: + :show-inheritance: + + .. automodule:: simpa.core.device_digital_twins.illumination_geometries.ithera_msot_acuity_illumination :members: :undoc-members: diff --git a/docs/source/simpa.core.device_digital_twins.pa_devices.rst b/docs/source/simpa.core.device_digital_twins.pa_devices.rst index dd796554..462b9051 100644 --- a/docs/source/simpa.core.device_digital_twins.pa_devices.rst +++ b/docs/source/simpa.core.device_digital_twins.pa_devices.rst @@ -22,3 +22,9 @@ pa\_devices :members: :undoc-members: :show-inheritance: + + +.. automodule:: simpa.core.device_digital_twins.pa_devices.photoacoustic_device + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/simpa.core.device_digital_twins.rst b/docs/source/simpa.core.device_digital_twins.rst index 5b25dcc9..a8aeb366 100644 --- a/docs/source/simpa.core.device_digital_twins.rst +++ b/docs/source/simpa.core.device_digital_twins.rst @@ -12,3 +12,8 @@ device\_digital\_twins simpa.core.device_digital_twins.detection_geometries simpa.core.device_digital_twins.illumination_geometries simpa.core.device_digital_twins.pa_devices + +.. automodule:: simpa.core.device_digital_twins.digital_device_twin_base + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/simpa.core.processing_components.multispectral.rst b/docs/source/simpa.core.processing_components.multispectral.rst index ef6f10e1..9a2e368b 100644 --- a/docs/source/simpa.core.processing_components.multispectral.rst +++ b/docs/source/simpa.core.processing_components.multispectral.rst @@ -10,3 +10,9 @@ multispectral :members: :undoc-members: :show-inheritance: + + +.. automodule:: simpa.core.processing_components.multispectral.multispectral_processing_algorithm + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/simpa.core.processing_components.rst b/docs/source/simpa.core.processing_components.rst index 7780b57d..52a88285 100644 --- a/docs/source/simpa.core.processing_components.rst +++ b/docs/source/simpa.core.processing_components.rst @@ -11,3 +11,8 @@ processing\_components simpa.core.processing_components.monospectral simpa.core.processing_components.multispectral + +.. automodule:: simpa.core.processing_components.processing_component_base + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/simpa.core.rst b/docs/source/simpa.core.rst index e86ea34b..78a560aa 100644 --- a/docs/source/simpa.core.rst +++ b/docs/source/simpa.core.rst @@ -13,6 +13,12 @@ core simpa.core.processing_components simpa.core.simulation_modules +.. automodule:: simpa.core.pipeline_element_base + :members: + :undoc-members: + :show-inheritance: + + .. automodule:: simpa.core.simulation :members: :undoc-members: diff --git a/docs/source/simpa.core.simulation_modules.reconstruction_module.rst b/docs/source/simpa.core.simulation_modules.reconstruction_module.rst index f14dd281..a875b39f 100644 --- a/docs/source/simpa.core.simulation_modules.reconstruction_module.rst +++ b/docs/source/simpa.core.simulation_modules.reconstruction_module.rst @@ -6,37 +6,43 @@ reconstruction\_module :undoc-members: :show-inheritance: -.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_module_delay_and_sum_adapter +.. automodule:: simpa.core.simulation_modules.reconstruction_module.delay_and_sum_adapter :members: :undoc-members: :show-inheritance: -.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_module_delay_multiply_and_sum_adapter +.. automodule:: simpa.core.simulation_modules.reconstruction_module.delay_multiply_and_sum_adapter :members: :undoc-members: :show-inheritance: -.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_module_signed_delay_multiply_and_sum_adapter +.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_adapter_base :members: :undoc-members: :show-inheritance: -.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_module_test_adapter +.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_test_adapter :members: :undoc-members: :show-inheritance: -.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_module_time_reversal_adapter +.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_utils :members: :undoc-members: :show-inheritance: -.. automodule:: simpa.core.simulation_modules.reconstruction_module.reconstruction_utils +.. automodule:: simpa.core.simulation_modules.reconstruction_module.signed_delay_multiply_and_sum_adapter + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: simpa.core.simulation_modules.reconstruction_module.time_reversal_adapter :members: :undoc-members: :show-inheritance: diff --git a/docs/source/simpa.core.simulation_modules.rst b/docs/source/simpa.core.simulation_modules.rst index 6ffa2e19..f2f2e85e 100644 --- a/docs/source/simpa.core.simulation_modules.rst +++ b/docs/source/simpa.core.simulation_modules.rst @@ -9,7 +9,12 @@ simulation\_modules .. toctree:: :maxdepth: 4 - simpa.core.simulation_modules.acoustic_forward_module - simpa.core.simulation_modules.optical_simulation_module + simpa.core.simulation_modules.acoustic_module + simpa.core.simulation_modules.optical_module simpa.core.simulation_modules.reconstruction_module simpa.core.simulation_modules.volume_creation_module + +.. automodule:: simpa.core.simulation_modules.simulation_module_base + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/simpa.core.simulation_modules.volume_creation_module.rst b/docs/source/simpa.core.simulation_modules.volume_creation_module.rst index 8fda1e0b..acf284c9 100644 --- a/docs/source/simpa.core.simulation_modules.volume_creation_module.rst +++ b/docs/source/simpa.core.simulation_modules.volume_creation_module.rst @@ -6,13 +6,19 @@ volume\_creation\_module :undoc-members: :show-inheritance: -.. automodule:: simpa.core.simulation_modules.volume_creation_module.volume_creation_module_model_based_adapter +.. automodule:: simpa.core.simulation_modules.volume_creation_module.model_based_adapter :members: :undoc-members: :show-inheritance: -.. automodule:: simpa.core.simulation_modules.volume_creation_module.volume_creation_module_segmentation_based_adapter +.. automodule:: simpa.core.simulation_modules.volume_creation_module.segmentation_based_adapter + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: simpa.core.simulation_modules.volume_creation_module.volume_creation_adapter_base :members: :undoc-members: :show-inheritance: diff --git a/docs/source/understanding_link.md b/docs/source/understanding_link.md new file mode 100644 index 00000000..0af7fad5 --- /dev/null +++ b/docs/source/understanding_link.md @@ -0,0 +1,2 @@ +```{include} understanding_simpa.md +``` \ No newline at end of file diff --git a/docs/source/understanding_simpa.md b/docs/source/understanding_simpa.md new file mode 100644 index 00000000..faa5603c --- /dev/null +++ b/docs/source/understanding_simpa.md @@ -0,0 +1,113 @@ +# Understanding SIMPA + +## Understanding Tags + +### What are Tags? + +In SIMPA, Tags are identifiers used to specify and categorize various settings and components within the simulation. +They act as keys in the configuration dictionaries, enabling a clear and organized way to define simulation parameters. +Tags ensure that the configuration is modular, readable, and easy to manage. + +### Purpose of Tags + +- **Organization**: Tags help in structuring the configuration settings systematically. +- **Flexibility**: They allow users to easily modify and extend configurations. +- **Reusability**: Tags facilitate the reuse of settings across different simulations. + +### How Tags Work + +Tags are used to identify different components and their settings within the configuration dictionaries. Each component +has a predefined set of tags associated with it. These tags are used to specify the parameters and properties of the +components. + +### What Tags are Available? + +The list of Tags available in SIMPA is very extensive (see [simpa.utils](simpa.utils.rst) for full list), due to the +level of customisation available to the user. To get to grips with the more commonly used Tags, we highly recommend +consulting the [examples](simpa_examples.rst). + +## Concept of Settings + +Settings in SIMPA are configurations that control the behavior of the simulation. They are used to specify parameters +and options for both the overall simulation and individual components of the simulation pipeline. Proper configuration +of these settings is crucial for accurate and efficient simulations. This documentation provides a foundational +understanding of these settings, allowing users to customize their simulations effectively. For more detailed +information on specific settings and components, users are encouraged to refer to the source code and additional +documentation provided within the SIMPA repository. + +### Global Settings + +Global settings apply to the entire simulation and include parameters that are relevant across multiple components. +These settings typically encompass general simulation properties such as physical constants and overarching simulation +parameters. + +#### Example of Global Settings + +- `Tags.SPACING_MM`: The voxel spacing in the simulation. +- `Tags.GPU`: Whether there is a GPU available to perform the computation. +- `Tags.WAVELENGTHS`: The wavelengths that will later be simulated. + +### Component Settings + +Component settings are specific to individual components within the simulation pipeline. Each component can have its own +set of settings that determine how it behaves. These settings allow for fine-grained control over the simulation +process, enabling customization and optimization for specific experimental conditions. + +#### Difference Between Global and Component Settings + +- **Scope**: + - Global settings affect the entire simulation framework. + - Component settings only influence the behavior of their respective components. + +- **Usage**: + - Global settings are defined once and applied universally. + - Component settings are defined for each component individually, allowing for component-specific customization. + +#### Implementation +For a given simulation, the overall simulation settings will first be created from the global settings. Then, each +components setting will be added. Overall, a dictionary instance will be created with all of the global settings as well +as the components settings as sub-dictionaries. + +## Available Component Settings + +The following list describes the available component settings for various components in the SIMPA framework. Each component may have a unique set of settings that control its behavior. + +### 1. Volume Creation + +Settings for the volume creation component, which defines the method used to create the simulation volume; and therefore +ultimately decides the properties of the simulation volume. It is added to the simulation settings using: +[set_volume_creator_settings](../../simpa/utils/settings.py). + +#### Examples of Volume Creation Settings +- `Tags.STRUCTURES`: When using the model based volume creation adapter, sets the structures to be fill the volume. +- `Tags.INPUT_SEGMENTATION_VOLUME`: When using the segmentation based volume creation adapter, the segmentation mapping +will be specified under this tag. + +### 2. Acoustic Model + +Settings for the acoustic forward model component, which simulates the propagation of acoustic waves. It is added to the +simulation settings using: [set_acoustic_settings](../../simpa/utils/settings.py). + +#### Examples of Acoustic Settings +- `Tags.KWAVE_PROPERTY_ALPHA_POWER`: The exponent in the exponential acoustic attenuation law of k-Wave. +- `Tags.RECORDMOVIE`: If true, a movie of the k-Wave simulation will be recorded. + +### 3. Optical Model + +Settings for the optical model component, which simulates the propagation of light through the medium. It is added to +the simulation settings using: [set_optical_settings](../../simpa/utils/settings.py). + +#### Examples of Optical Settings +- `Tags.OPTICAL_MODEL_NUMBER_PHOTONS`: The number of photons used in the optical simulation. +- `Tags.LASER_PULSE_ENERGY_IN_MILLIJOULE`: The laser pulse energy used in the optical simulation. + +### 4. Reconstruction model + +Settings for the reconstruction model, which reconstructs the image from the simulated signals. It is added to the +simulation settings using: [set_reconstruction_settings](../../simpa/utils/settings.py). + +#### Examples of Reconstruction Settings + +- `Tags.RECONSTRUCTION_BMODE_AFTER_RECONSTRUCTION`: Specifies whether an envelope detection should be performed after +reconstruction. +- `Tags.RECONSTRUCTION_PERFORM_BANDPASS_FILTERING`: Whether bandpass filtering should be applied or not. diff --git a/simpa/core/simulation_modules/simulation_module_base.py b/simpa/core/simulation_modules/simulation_module_base.py index 1ac50a33..39415038 100644 --- a/simpa/core/simulation_modules/simulation_module_base.py +++ b/simpa/core/simulation_modules/simulation_module_base.py @@ -41,4 +41,4 @@ def get_additional_flags(self) -> List[str]: if Tags.ADDITIONAL_FLAGS in self.component_settings: for flag in self.component_settings[Tags.ADDITIONAL_FLAGS]: cmd.append(str(flag)) - return cmd \ No newline at end of file + return cmd diff --git a/simpa_tests/automatic_tests/test_additional_flags.py b/simpa_tests/automatic_tests/test_additional_flags.py index c8ad88b1..95e6d078 100644 --- a/simpa_tests/automatic_tests/test_additional_flags.py +++ b/simpa_tests/automatic_tests/test_additional_flags.py @@ -1,3 +1,7 @@ +# SPDX-FileCopyrightText: 2021 Division of Intelligent Medical Systems, DKFZ +# SPDX-FileCopyrightText: 2021 Janek Groehl +# SPDX-License-Identifier: MIT + import unittest import numpy as np @@ -9,17 +13,18 @@ class TestAdditionalFlags(unittest.TestCase): def setUp(self) -> None: self.additional_flags = ('-l', '-a') self.settings = Settings() - + def test_get_cmd_mcx_reflectance_adapter(self): self.settings.set_optical_settings({ Tags.OPTICAL_MODEL_BINARY_PATH: '.', Tags.ADDITIONAL_FLAGS: self.additional_flags }) - mcx_reflectance_adapter = MCXReflectanceAdapter(global_settings=self.settings) + mcx_reflectance_adapter = MCXReflectanceAdapter(global_settings=self.settings) cmd = mcx_reflectance_adapter.get_command() for flag in self.additional_flags: - self.assertIn(flag, cmd, f"{flag} was not in command returned by mcx reflectance adapter but was defined as additional flag") - + self.assertIn( + flag, cmd, f"{flag} was not in command returned by mcx reflectance adapter but was defined as additional flag") + def test_get_cmd_mcx_adapter(self): self.settings.set_optical_settings({ Tags.OPTICAL_MODEL_BINARY_PATH: '.', @@ -28,8 +33,9 @@ def test_get_cmd_mcx_adapter(self): mcx_adapter = MCXAdapter(global_settings=self.settings) cmd = mcx_adapter.get_command() for flag in self.additional_flags: - self.assertIn(flag, cmd, f"{flag} was not in command returned by mcx adapter but was defined as additional flag") - + self.assertIn( + flag, cmd, f"{flag} was not in command returned by mcx adapter but was defined as additional flag") + def test_get_cmd_kwave_adapter(self): self.settings.set_acoustic_settings({ Tags.ADDITIONAL_FLAGS: self.additional_flags @@ -37,16 +43,19 @@ def test_get_cmd_kwave_adapter(self): kwave_adapter = KWaveAdapter(global_settings=self.settings) cmd = generate_matlab_cmd("./matlab.exe", "simulate_2D.m", "my_hdf5.mat", kwave_adapter.get_additional_flags()) for flag in self.additional_flags: - self.assertIn(flag, cmd, f"{flag} was not in command returned by kwave adapter but was defined as additional flag") + self.assertIn( + flag, cmd, f"{flag} was not in command returned by kwave adapter but was defined as additional flag") def test_get_cmd_time_reversal_adapter(self): self.settings.set_reconstruction_settings({ Tags.ADDITIONAL_FLAGS: self.additional_flags }) time_reversal_adapter = TimeReversalAdapter(global_settings=self.settings) - cmd = generate_matlab_cmd("./matlab.exe", "time_reversal_2D.m", "my_hdf5.mat", time_reversal_adapter.get_additional_flags()) + cmd = generate_matlab_cmd("./matlab.exe", "time_reversal_2D.m", "my_hdf5.mat", + time_reversal_adapter.get_additional_flags()) for flag in self.additional_flags: - self.assertIn(flag, cmd, f"{flag} was not in command returned by time reversal adapter but was defined as additional flag") + self.assertIn( + flag, cmd, f"{flag} was not in command returned by time reversal adapter but was defined as additional flag") if __name__ == '__main__':