光子学和声学仿真和图像处理工具包 (SIMPA)

SIMPA 旨在通过为关键建模步骤（例如体积生成）提供适配器来促进光学和声学成像模式的真实图像模拟；光学建模；声学建模；和图像重建。SIMPA 在实现光学和声学正反模型的各种模块之间提供通信层。非专家可以使用该工具包以端到端的方式从默认参数创建合理的模拟。为领域专家提供了根据其特定用例和工具要求设置高度可定制的管道的功能。介绍 SIMPA 包括可视化和解释的论文可以在这里找到：https ://doi.org/10.1117/1.JBO.27.8.083010

• 入门
• 模拟示例
• 文档
• 贡献
• 性能分析
• 故障排除
• 引文

该工具包仍在开发中，因此未经过全面测试，可能包含错误。请报告您在我们的问题跟踪器中发现的任何问题：https ://github.com/IMSY-DKFZ/simpa/issues 。还要确保仔细检查光学和声学组织特性的所有值范围，并评估所有模拟结果的合理性。

入门

为了在您的项目中使用 SIMPA，必须安装 SIMPA 以及使实际模拟成为可能的外部工具。最后，为了连接一切，SIMPA 必须找到您想要使用的模拟模块的所有二进制文件。SIMPA 路径管理解决了这个问题。

• SIMPA 安装说明
• 外部工具安装说明
• 路径管理

SIMPA 安装说明

安装 SIMPA 的推荐方法是从 GitHub 存储库手动安装，请按照步骤 1 - 3 操作：

1. git clone https://github.com/IMSY-DKFZ/simpa.git
2. cd simpa
3. git checkout main
4. git pull

现在在您刚刚下载的“simpa”文件夹中打开一个 python 实例。确保您已激活首选虚拟环境（我们还推荐使用 python 3.8）

1. pip install .
2. 通过使用python然后测试安装是否有效import simpaexit()

如果没有出现错误消息，您现在可以在项目中使用 SIMPA。

您还可以使用 pip 安装 SIMPA。只需运行：

pip install simpa

您还需要手动安装 pytorch 库才能使用 SIMPA 的所有功能。为此，使用pytorch网站工具确定要安装哪个版本： https ://pytorch.org/get-started/locally/

外部工具安装说明

为了获得完整的 SIMPA 功能，您应该安装所有使光学和声学模拟成为可能的第三方工具包。

mcx（光学正向模型）

下载合适的可执行文件或从以下来源自行构建：

http://mcx.space/

为了获得对我们实现的所有自定义源的访问权限，请从以下 mcx Github fork 自己构建 mcx： https ://github.com/IMSY-DKFZ/mcx

对于安装，请按照步骤 1-4：

1. git clone https://github.com/IMSY-DKFZ/mcx.git
2. cd mcx/src
3. 根据您的 GPU在MAKEFILE第 111 行调整 sm 版本。
4. make

构建的二进制文件可以在src/bin. 请注意，如果您无法使用特定于 GPU 的 sm 版本构建 mcx，则需要安装更新的 NVIDIA 驱动程序和 nvcc 工具包。一种选择是通过在 conda 环境中安装 cuda conda install cuda -c nvidia。请注意，将 mcx-cl 与 MCX 适配器一起使用可能存在兼容性问题，因为 SIMPA 开发人员未测试和支持此用例。

k-Wave（声学正向模型）

请按照以下步骤操作并使用 k-Wave 安装说明获得更多（更好的）指导：

http://www.k-wave.org/

1. 安装 MATLAB，并至少激活核心、图像处理和并行计算工具箱。
2. 下载 kwave 工具箱
3. 将 kWave 工具箱基本路径添加到 MATLAB 中的工具箱路径
4. 从此用户论坛帖子http://www.k-wave.org/forum/topic/alpha-version-of-kwavearray-off-grid-sources中给出的链接下载 kWaveArray 添加
5. 将 kWaveArray 文件夹也添加到 MATLAB 中的工具箱路径中
6. 如果需要：下载 CPP 和 CUDA 二进制文件并将它们放在 k-Wave/binaries 文件夹中
7. 记下matlab可执行文件的系统路径。

路径管理

作为在不同数值正演模型和处理工具之间充当通信层的流水线工具，SIMPA 需要在本地硬盘上配置这些工具的路径。为此，我们实现了PathManager可以使用 from simpa.utils import PathManager. PathManager按以下顺序在以下位置查找path_config.env文件（就像我们在 中提供的文件一样）：simpa_examples

1. 你给 PathManager 的可选路径
2. 你的 $HOME$ 目录
3. 当前工作目录
4. SIMPA 主目录路径

请按照文件夹中path_config.env文件中的说明进行操作simpa_examples。

模拟示例

为了开始实际模拟，SIMPA 提供了一个简单模拟脚本的示例包，用于构建您的自定义模拟。 如果您安装了 MCX，最小的光学模拟是一个不错的开始。

通常，以下伪代码演示了模拟管道的构建和运行：

import simpa as sp

# Create general settings 
settings = sp.Settings(general_settings)

# Create specific settings for each pipeline element 
# in the simulation pipeline
settings.set_volume_creation_settings(volume_creation_settings)
settings.set_optical_settings(optical_settings)
settings.set_acoustic_settings(acoustic_settings)
settings.set_reconstruction_settings(reconstruction_settings)

# Set the simulation pipeline
simulation_pipeline = [sp.VolumeCreatorModule(settings),
    sp.OpticalForwardModule(settings),
    sp.AcousticForwardModule(settings),
    sp.ReconstructionModule(settings)]
    
# Choose a PA device with device position in the volume
device = sp.CustomDevice()

# Simulate the pipeline
sp.simulate(simulation_pipeline, settings, device)

文档

SIMPA 文档的更新版本可以在https://simpa.readthedocs.io/en/develop找到。

构建文档

从头开始构建 SIMPA 文档也很容易。安装成功后，如果您想确保拥有最新的文档，您应该在命令行中执行以下步骤：

1. 导航到simpa/docs目录
2. 如果您希望文档具有https://readthedocs.org/样式，请键入pip install sphinx-rtd-theme
3. 类型make html
4. 使用您喜欢的浏览器打开目录index.html中的文件。simpa/docs/build/html

如何贡献

请在我们的贡献指南中找到有关如何贡献的更详细描述以及代码样式参考 。

要为 SIMPA 做出贡献，请 fork SIMPA github 存储库并创建一个包含您建议更改的分支的拉取请求。然后，核心开发人员将审查建议的更改并将其集成到代码库中。

请确保您已包含代码的单元测试，并且所有先前的测试仍在运行。

每周五在欧洲中部时间/欧洲中部标准时间 10:00 举行定期 SIMPA 状态会议，非常欢迎您参与并提出任何问题或建议新功能。如果你想加入这个会议，写一个核心开发者。

请参阅创建拉取请求的 github 指南：https ://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests

性能分析

您想知道仿真管道的哪些部分花费的时间最多吗？如果是这种情况，那么您可以使用以下命令来分析您的模拟脚本的执行情况。您只需要将myscript名称替换为您的脚本名称。

python -m cProfile -o myscript.cprof myscript.py

pyprof2calltree -k -i myscript.cprof

故障排除

在本节中，列出了已知问题及其解决方案（如果有）：

1. 使用 k-Wave 二进制文件时读取 hdf5 文件时出错：

如果您遇到类似以下的错误：

Error using h5readc
The filename specified was either not found on the MATLAB path or it contains unsupported characters.

在 k-Wave 论坛的这个帖子中查找解决方案。

引文

如果您使用 SIMPA 工具，如果您引用我们在生物医学光学杂志上的期刊出版物，我们将不胜感激：

Gröhl、Janek、Kris K. Dreher、Melanie Schellenberg、Tom Rix、Niklas Holzwarth、Patricia Vieten、Leonardo Ayala、Sarah E. Bohndiek、Alexander Seitel 和 Lena Maier-Hein。“SIMPA：用于光子学和声学仿真和图像处理的开源工具包。” 生物医学光学杂志27，没有。8（2022）。

@article{2022simpatoolkit,
  title={SIMPA: an open-source toolkit for simulation and image processing for photonics and acoustics},
  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},
  journal={Journal of Biomedical Optics},
  volume={27},
  number={8},
  year={2022},
  publisher={SPIE}
}