Merge branch 'develop' into T323_clean_logging

IMSY-DKFZ · Aug 15, 2024 · d581d0a · d581d0a
2 parents 4f35ab3 + 85463ef
commit d581d0a
Show file tree

Hide file tree

Showing 16 changed files with 224 additions and 21 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,2 @@
+```{include} understanding_simpa.md
+```
diff --git a/docs/source/understanding_simpa.md 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
@@ -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
+        return cmd