{"id":19825658,"url":"https://github.com/imsy-dkfz/simpa","last_synced_at":"2025-04-04T07:08:08.016Z","repository":{"id":37087855,"uuid":"337741424","full_name":"IMSY-DKFZ/simpa","owner":"IMSY-DKFZ","description":"The Simulation and Image Processing for Photonics and Acoustics (SIMPA) toolkit.","archived":false,"fork":false,"pushed_at":"2024-12-18T17:14:20.000Z","size":13450,"stargazers_count":89,"open_issues_count":130,"forks_count":18,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-02-22T13:44:01.188Z","etag":null,"topics":["acoustics","image-processing","photoacoustic-imaging","photonics","research-software","simulation"],"latest_commit_sha":null,"homepage":"https://simpa.readthedocs.io/en/main/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IMSY-DKFZ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-10T14:01:42.000Z","updated_at":"2025-02-18T12:49:01.000Z","dependencies_parsed_at":"2024-03-04T14:40:07.996Z","dependency_job_id":"55b9b1fc-e7d3-4ffa-bb2c-366a1c398c53","html_url":"https://github.com/IMSY-DKFZ/simpa","commit_stats":{"total_commits":1079,"total_committers":20,"mean_commits":53.95,"dds":0.6098239110287302,"last_synced_commit":"78d1f8bd1d9a7a22defae5de4874f2b3beec4e94"},"previous_names":["cami-dkfz/simpa"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IMSY-DKFZ%2Fsimpa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IMSY-DKFZ%2Fsimpa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IMSY-DKFZ%2Fsimpa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IMSY-DKFZ%2Fsimpa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IMSY-DKFZ","download_url":"https://codeload.github.com/IMSY-DKFZ/simpa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135144,"owners_count":20889421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acoustics","image-processing","photoacoustic-imaging","photonics","research-software","simulation"],"created_at":"2024-11-12T11:08:19.965Z","updated_at":"2025-04-04T07:08:07.984Z","avatar_url":"https://github.com/IMSY-DKFZ.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![Logo](https://github.com/IMSY-DKFZ/simpa/raw/main/docs/source/images/simpa_logo.png?raw=true \"SIMPA Logo\")\n\n[![Documentation Status](https://readthedocs.org/projects/simpa/badge/?version=develop)](https://simpa.readthedocs.io/en/develop/?badge=develop)\n![Build Status](https://github.com/IMSY-DKFZ/simpa/actions/workflows/automatic_testing.yml/badge.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/IMSY-DKFZ/simpa/blob/main/LICENSE.md)\n[![Pypi Badge](https://img.shields.io/pypi/v/simpa)](https://pypi.org/project/simpa/)\n[![PyPI downloads](https://img.shields.io/pypi/dw/simpa?color=gr\u0026label=pypi%20downloads)](https://pypi.org/project/simpa/)\n\n\u003c/div\u003e\n\n# The toolkit for Simulation and Image Processing for Photonics and Acoustics (SIMPA)\n\nSIMPA aims to facilitate realistic image simulation for optical and acoustic imaging modalities by\nproviding adapters to crucial modelling steps, such as volume generation; optical modelling; acoustic\nmodelling; and image reconstruction. SIMPA provides a communication layer between various modules\nthat implement optical and acoustic forward and inverse models.\nNon-experts can use the toolkit to create sensible simulations from default parameters in an end-to-end fashion. Domain experts are provided with the functionality to set up a highly customisable\npipeline according to their specific use cases and tool requirements.\nThe paper that introduces SIMPA including visualisations and explanations can be found here: [https://doi.org/10.1117/1.JBO.27.8.083010](https://doi.org/10.1117/1.JBO.27.8.083010)\n\n* [Getting started](#getting-started)\n* [Simulation examples](#simulation-examples)\n* [Documentation](#documentation)\n* [Reproducibility](#reproducibility)\n* [Contributing](#how-to-contribute)\n* [Performance profiling](#performance-profiling)\n* [Troubleshooting](#troubleshooting)\n* [Citation](#citation)\n* [Funding](#funding)\n\nThe toolkit is still under development and is thus not fully tested and may contain bugs. \nPlease report any issues that you find in our Issue Tracker: https://github.com/IMSY-DKFZ/simpa/issues. \nAlso make sure to double check all value ranges of the optical and acoustic tissue properties \nand to assess all simulation results for plausibility.\n\n# Getting started\n\nIn order to use SIMPA in your project, SIMPA has to be installed as well as the external tools that make the actual simulations possible.\nFinally, to connect everything, SIMPA has to find all the binaries of the simulation modules you would like to use.\nThe SIMPA path management takes care of that.\n\n* [SIMPA installation instructions](#simpa-installation-instructions)\n* [External tools installation instructions](#external-tools-installation-instructions)\n* [Path Management](#path-management)\n* [Testing](#run-manual-tests)\n\n## SIMPA installation instructions\n\nThe recommended way to install SIMPA is a manual installation from the GitHub repository, please follow steps 1 - 3:\n\n1. `git clone https://github.com/IMSY-DKFZ/simpa.git`\n2. `cd simpa`\n3. `git checkout main`\n4. `git pull`\n\nNow open a python instance in the 'simpa' folder that you have just downloaded. Make sure that you have your preferred\nvirtual environment activated (we also recommend python 3.10)\n1. `pip install .` or `pip install -e .` for an editable mode. \n2. Test if the installation worked by using `python` followed by `import simpa` then `exit()`\n\nIf no error messages arise, you are now setup to use SIMPA in your project.\n\nYou can also install SIMPA with pip. Simply run:\n\n`pip install simpa`\n\nYou also need to manually install the pytorch library to use all features of SIMPA.\nTo this end, use the pytorch website tool to figure out which version to install:\n[https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)\n\n## External tools installation instructions\n\nIn order to get the full SIMPA functionality, you should install all third party toolkits that make the optical and \nacoustic simulations possible. \n\n### mcx (Optical Forward Model)\n\nDownload the latest nightly build of [mcx](http://mcx.space/) on [this page](http://mcx.space/nightly/github/) for your operating system:\n\n- Linux: `mcx-linux-x64-github-latest.zip`\n- MacOS: `mcx-macos-x64-github-latest.zip`\n- Windows: `mcx-windows-x64-github-latest.zip`\n\nThen extract the files and set `MCX_BINARY_PATH=/.../mcx/bin/mcx` in your path_config.env.\n\n### k-Wave (Acoustic Forward Model)\n\nPlease follow the following steps and use the k-Wave install instructions \nfor further (and much better) guidance under:\n\n[http://www.k-wave.org/](http://www.k-wave.org/)\n\n1. Install MATLAB with the core, image processing and parallel computing toolboxes activated at the minimum.\n2. Download the kWave toolbox (version \u003e= 1.4)\n3. Add the kWave toolbox base path to the toolbox paths in MATLAB\n4. If wanted: Download the CPP and CUDA binary files and place them in the k-Wave/binaries folder\n5. Note down the system path to the `matlab` executable file.\n\n## Path management\n\nAs a pipelining tool that serves as a communication layer between different numerical forward models and\nprocessing tools, SIMPA needs to be configured with the paths to these tools on your local hard drive.\nYou have a couple of options to define the required path variables. \n### Option 1: \nEnsure that the environment variables defined in `simpa_examples/path_config.env.example` are accessible to your script during runtime. This can be done through any method you prefer, as long as the environment variables are accessible through `os.environ`. \n### Option 2:\nImport the `PathManager` class to your project using\n`from simpa.utils import PathManager`. If a path to a `.env` file is not provided, the `PathManager` looks for a `path_config.env` file (just like the\none we provided in the `simpa_examples/path_config.env.example`) in the following places, in this order:\n1. The optional path you give the PathManager\n2. Your $HOME$ directory\n3. The current working directory\n4. The SIMPA home directory path\n   \nFor this option, please follow the instructions in the `simpa_examples/path_config.env.example` file. \n\n## Run manual tests\nTo check the success of your installation ot to assess how your contributions affect the Simpa simulation outcomes, you can run the manual tests automatically. Install the testing requirements by doing `pip install .[testing]` and run the `simpa_tests/manual_tests/generate_overview.py` file. This script runs all manual tests and generates both a markdown and an HTML file that compare your results with the reference results.\n\n# Simulation examples\n\nTo get started with actual simulations, SIMPA provides an [example package](simpa_examples) of simple simulation \nscripts to build your custom simulations upon. The [minimal optical simulation](simpa_examples/minimal_optical_simulation.py)\nis a nice start if you have MCX installed.\n\nGenerally, the following pseudo code demonstrates the construction and run of a simulation pipeline:\n\n```python\nimport simpa as sp\n\n# Create general settings \nsettings = sp.Settings(general_settings)\n\n# Create specific settings for each pipeline element \n# in the simulation pipeline\nsettings.set_volume_creation_settings(volume_creation_settings)\nsettings.set_optical_settings(optical_settings)\nsettings.set_acoustic_settings(acoustic_settings)\nsettings.set_reconstruction_settings(reconstruction_settings)\n\n# Set the simulation pipeline\nsimulation_pipeline = [sp.VolumeCreationModule(settings),\n                       sp.OpticalModule(settings),\n                       sp.AcousticModule(settings),\n                       sp.ReconstructionModule(settings)]\n    \n# Choose a PA device with device position in the volume\ndevice = sp.CustomDevice()\n\n# Simulate the pipeline\nsp.simulate(simulation_pipeline, settings, device)\n```\n\n# Reproducibility\n\nFor reproducibility, we provide the exact version number including the commit hash in the simpa output file.\nThis can be accessed via `simpa.__version__` or by checking the tag `Tags.SIMPA_VERSION` in the output file.\nThis way, you can always trace back the exact version of the code that was used to generate the simulation results.\n\n# Documentation\n\nThe updated version of the SIMPA documentation can be found at [https://simpa.readthedocs.io/en/develop](https://simpa.readthedocs.io/en/develop).\n\n## Building the documentation\n\nIt is also easily possible to build the SIMPA documentation from scratch.\nWhen the installation succeeded, and you want to make sure that you have the latest documentation\nyou should do the following steps in a command line:\n\n1. Make sure that you've installed the optional dependencies needed for the documentation by running `pip install .[docs]`\n2. Navigate to the `simpa/docs` directory\n2. If you would like the documentation to have the https://readthedocs.org/ style, type `pip install sphinx-rtd-theme`\n3. Type `make html`\n4. Open the `index.html` file in the `simpa/docs/build/html` directory with your favourite browser.\n\n# How to contribute\n\nPlease find a more detailed description of how to contribute as well as code style references in our\n[contribution guidelines](CONTRIBUTING.md).\n\nTo contribute to SIMPA, please fork the SIMPA github repository and create a pull request with a branch containing your \nsuggested changes. The core developers will then review the suggested changes and integrate these into the code \nbase.\n\nPlease make sure that you have included unit tests for your code and that all previous tests still run through. Please also run the pre-commit hooks and make sure they are passing.\nDetails are found in our [contribution guidelines](CONTRIBUTING.md).\n\nThere is a regular SIMPA status meeting every Friday on even calendar weeks at 10:00 CET/CEST, and you are very welcome to participate and\nraise any issues or suggest new features. If you want to join this meeting, write one of the core developers.\n\nPlease see the github guidelines for creating pull requests: [https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)\n\n\n# Performance profiling\n\nWhen changing the SIMPA core, e.g., by refactoring/optimizing, or if you are curious about how fast your machine runs\nSIMPA, you can run the SIMPA [benchmarking scripts](simpa_examples/benchmarking/run_benchmarking.sh). Make sure to install the necessary dependencies via \n`pip install .[profile]` and then run:\n\n```bash\nbash ./run_benchmark.sh\n```\n\nonce for checking if it works and then parse [--number 100] to run it at eg 100 times for actual benchmarking.\nPlease see [benchmarking.md](docs/source/benchmarking.md) for a complete explanation.\n\n\n# Understanding SIMPA\n\n**Tags** are identifiers in SIMPA used to categorize settings and components within simulations, making configurations\nmodular, readable, and manageable. Tags offer organizational, flexible, and reusable benefits by acting as keys in\nconfiguration dictionaries.\n\n**Settings** in SIMPA control simulation behavior. They include:\n\n- **Global Settings**: Apply to the entire simulation, affecting overall properties and parameters.\n- **Component Settings**: Specific to individual components, allowing for detailed customization and optimization of\neach part of the simulation.\n\nSettings are defined in a hierarchical structure, where global settings are established first, followed by\ncomponent-specific settings. This approach ensures comprehensive and precise control over the simulation process.\nFor detailed information, users can refer to the [understanding SIMPA documentation](./docs/source/understanding_simpa.md).\n\n# Troubleshooting\n\nIn this section, known problems are listed with their solutions (if available):\n\n## 1. Error reading hdf5-files when using k-Wave binaries:\n   \nIf you encounter an error similar to:\n\n    Error using h5readc\n    The filename specified was either not found on the MATLAB path or it contains unsupported characters.\n\nLook 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).  \n\n## 2. KeyError: 'time_series_data'\n\nThis is the error which will occur for ANY k-Wave problem. For the actual root of the problem, please either look above in\nthe terminal for the source of the bug or run the scripts in Matlab to find it manually.\n      \n# Citation\n\nIf you use the SIMPA tool, we would appreciate if you cite our Journal publication in the Journal of Biomedical Optics:\n\nGröhl, Janek, Kris K. Dreher, Melanie Schellenberg, Tom Rix, Niklas Holzwarth, Patricia Vieten, Leonardo Ayala, Sarah E. Bohndiek, Alexander Seitel, and Lena Maier-Hein. *\"SIMPA: an open-source toolkit for simulation and image processing for photonics and acoustics.\"* **Journal of Biomedical Optics** 27, no. 8 (2022).\n\n```Bibtex\n@article{2022simpatoolkit,\n  title={SIMPA: an open-source toolkit for simulation and image processing for photonics and acoustics},\n  author={Gr{\\\"o}hl, Janek and Dreher, Kris K and Schellenberg, Melanie and Rix, Tom and Holzwarth, Niklas and Vieten, Patricia and Ayala, Leonardo and Bohndiek, Sarah E and Seitel, Alexander and Maier-Hein, Lena},\n  journal={Journal of Biomedical Optics},\n  volume={27},\n  number={8},\n  year={2022},\n  publisher={SPIE}\n}\n```\n\n# Funding\n\nThis project has received funding from the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation programme (grant agreement No. [101002198]).\n\n![ERC](https://github.com/IMSY-DKFZ/simpa/raw/main/docs/source/images/LOGO_ERC-FLAG_EU_.jpg \"ERC\")\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimsy-dkfz%2Fsimpa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimsy-dkfz%2Fsimpa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimsy-dkfz%2Fsimpa/lists"}