From 90b3be96e1a2de97bd69077d90a38154365bb115 Mon Sep 17 00:00:00 2001 From: Friso Grace Date: Mon, 15 Jul 2024 15:56:26 +0200 Subject: [PATCH 1/4] Added documentation for simpa settings and tags --- docs/source/Understanding_SIMPA.md | 111 +++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/source/Understanding_SIMPA.md diff --git a/docs/source/Understanding_SIMPA.md b/docs/source/Understanding_SIMPA.md new file mode 100644 index 00000000..b0bca20a --- /dev/null +++ b/docs/source/Understanding_SIMPA.md @@ -0,0 +1,111 @@ +# SIMPA Documentation + +## 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). + +- `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. From e4506cce25f47c4fd482213b72a8a47187e29a7b Mon Sep 17 00:00:00 2001 From: Friso Grace Date: Tue, 16 Jul 2024 13:52:26 +0200 Subject: [PATCH 2/4] adding link to index.rst --- docs/source/index.rst | 1 + docs/source/understanding_link.md | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 docs/source/understanding_link.md diff --git a/docs/source/index.rst b/docs/source/index.rst index 041f3cfc..603eab8a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,6 +21,7 @@ pipeline according to their specific use cases and tool requirements. intro_link contributing_link + understanding_link.md =================================== diff --git a/docs/source/understanding_link.md b/docs/source/understanding_link.md new file mode 100644 index 00000000..1766fc77 --- /dev/null +++ b/docs/source/understanding_link.md @@ -0,0 +1,2 @@ +```{include} introduction.md +``` \ No newline at end of file From 72640f6f6044d5f4538d5d1da2ac113250e865c0 Mon Sep 17 00:00:00 2001 From: Friso Grace Date: Fri, 26 Jul 2024 17:01:26 +0200 Subject: [PATCH 3/4] Adding a short section to the readme to help people get a brief overview before having to read the whole doc --- README.md | 21 +++++++++++++++++++ docs/source/understanding_link.md | 2 +- ...anding_SIMPA.md => understanding_simpa.md} | 2 +- 3 files changed, 23 insertions(+), 2 deletions(-) rename docs/source/{Understanding_SIMPA.md => understanding_simpa.md} (99%) diff --git a/README.md b/README.md index 9945dfb7..9672428b 100755 --- a/README.md +++ b/README.md @@ -191,6 +191,22 @@ You simply need to replace the `myscript` name with your script name. `pyprof2calltree -k -i myscript.cprof` +# 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): @@ -203,6 +219,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/understanding_link.md b/docs/source/understanding_link.md index 1766fc77..0af7fad5 100644 --- a/docs/source/understanding_link.md +++ b/docs/source/understanding_link.md @@ -1,2 +1,2 @@ -```{include} introduction.md +```{include} understanding_simpa.md ``` \ No newline at end of file diff --git a/docs/source/Understanding_SIMPA.md b/docs/source/understanding_simpa.md similarity index 99% rename from docs/source/Understanding_SIMPA.md rename to docs/source/understanding_simpa.md index b0bca20a..b45d394f 100644 --- a/docs/source/Understanding_SIMPA.md +++ b/docs/source/understanding_simpa.md @@ -1,4 +1,4 @@ -# SIMPA Documentation +# Understanding SIMPA ## Understanding Tags From 00ff7a7a3f8833d528dfd88fd0cd33b4d44048c7 Mon Sep 17 00:00:00 2001 From: Kris Dreher Date: Tue, 13 Aug 2024 16:16:19 +0200 Subject: [PATCH 4/4] Updated docs --- docs/source/index.rst | 2 +- docs/source/understanding_simpa.md | 2 ++ .../simulation_module_base.py | 2 +- .../automatic_tests/test_additional_flags.py | 27 ++++++++++++------- 4 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 6adffb2c..1472bfc4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,9 +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/understanding_simpa.md b/docs/source/understanding_simpa.md index b45d394f..faa5603c 100644 --- a/docs/source/understanding_simpa.md +++ b/docs/source/understanding_simpa.md @@ -106,6 +106,8 @@ the simulation settings using: [set_optical_settings](../../simpa/utils/settings 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__':