MultiscaleRun

MultiscaleRun是一个Python包，用于在不同尺度上运行脑细胞模拟。它协调多个脑模拟器（如Neuron和STEPS）以及求解器（如AstroVascPy，用于脑血流）之间的耦合。该包还嵌入了一个Julia求解器来模拟星形胶质细胞的活性。

Python包包含一个名为multiscale-run的程序，允许您从开始到结束运行和分析多尺度模拟。

如何在BB5上加载MultiscaleRun？

multiscale-run已在BB5上安装，但首先需要分配一个计算节点以减轻登录节点上的负载，例如

salloc -N 1 -A proj40 -p prod --exclusive --mem=0 -t 02:00:00 --cpus-per-task=2 --constraint=clx

作为模块（推荐）

module load unstable py-multiscale-run

作为spack包

spack install py-multiscale-run@develop
spack load py-multiscale-run

推荐使用spack环境在仅包含MultiscaleRun所需的spack包的独立环境中工作。有关spack环境的更多信息

:rainbow: 这可能在您的spack机器上也能工作！

如何使用MultiscaleRun可执行文件？

multiscale-run可执行文件提供了一些命令来初始化、配置和执行模拟

设置新的模拟

multiscale-run init /path/to/my-sim

此命令在/path/to/my-sim中创建以下文件，提供电路、配置文件和运行时依赖项。

• circuit_config.json：要模拟的电路描述。
• node_sets.json：作为不同报告或刺激目标单元格的子集。另请参阅https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#node-sets-file
• simulation_config.json：将电路上的模拟定义联系起来，请参阅下面的模拟配置部分以了解专门的"multiscale_run"部分。
• simulation.sbatch：在BB5上启动模拟的SLURM脚本的示例。
• postproc.ipynb：利用模拟结果构建报告的Jupyter笔记本示例。

生成的设置已准备好进行计算，但您可以根据需要浏览和调整JSON配置文件，特别是simulation_config.json文件的"multiscale_run"部分。

:ledger: 有关更多信息，请参阅multiscale-run init --help

验证模拟配置

此命令执行一系列检查以识别配置中的常见错误。建议在开始模拟之前执行此操作。

multiscale-run check [/path/to/my/sim]

计算模拟

在当前机器/分配上

multiscale-run compute [/path/to/my-sim]

:ledger: 要使用多个排名，请使用srun -n X multiscale-run compute，其中X是排名数。请注意，步骤要求这是2的幂。

:ledger: 有关更多信息，请参阅multiscale-run compute --help

:exclamation: 如果尚未加载，您可能需要在BB5上加载intel-oneapi-mkl模块，否则在运行compute阶段时可能会遇到以下错误：libmkl_intel_thread.so.1: undefined symbol: omp_get_num_procs

在模拟过程中将创建三个更多文件夹

• cache：保留一些缓存的通信矩阵，对于后续运行很有用。
• mesh：steps的网格文件。如果文件夹缺失，将即时生成标准网格。
• RESULTS：模拟的结果。各种数据记录在此处的HDF5文件中。变量基于神经元。MultiscaleRun模仿Neurodamus结果文件的结构，以便可以使用相同的方法进行后处理。

:为了效率起见，MultiscaleRun结果文件在模拟开始时用0填充。因此，如果模拟提前终止，这些文件将充满0，直到模拟终止的时间步。

在SLURM集群上

sbatch simulation.sbatch

其他操作

自定义神经元机制

此操作克隆Neurodamus mod文件库以进行本地编辑。

multiscale-run edit-mod-files [/path/to/my-sim]

故障排除

命令build_neurodamus.sh mod可能因以下错误而失败

=> LINKING shared library ./libnrnmech.so
/usr/bin/ld: /gpfs/bbp.cscs.ch/ssd/apps/bsd/2024-02-01/stage_applications/install_oneapi-2023.2.0-skylake/neuron-9.0.a15-lrspl6/lib/libnrniv.so: unable to initialize decompress status for section .debug_info
/usr/bin/ld: /gpfs/bbp.cscs.ch/ssd/apps/bsd/2024-02-01/stage_applications/install_oneapi-2023.2.0-skylake/neuron-9.0.a15-lrspl6/lib/libnrniv.so: unable to initialize decompress status for section .debug_info
/gpfs/bbp.cscs.ch/ssd/apps/bsd/2024-02-01/stage_applications/install_oneapi-2023.2.0-skylake/neuron-9.0.a15-lrspl6/lib/libnrniv.so: file not recognized: File format not recognized
icpx: error: linker command failed with exit code 1 (use -v to see invocation)
make: *** [/gpfs/bbp.cscs.ch/ssd/apps/bsd/2024-02-01/stage_applications/install_oneapi-2023.2.0-skylake/neuron-9.0.a15-lrspl6/bin/nrnmech_makefile:133: mech_lib_shared] Error 1

这是因为Neuron是用Intel oneAPI编译器构建的，但环境中没有可用的编译器。在BB5上加载适当的模块可能修复此问题：module load unstable intel-oneapi-compilers

将BlueConfig转换为SONATA兼容的JSON文件

1. 使用multiscale-run virtualenv操作设置开发环境
2. 克隆bluepy-configfile存储库
3. 转到存储库并执行：pip install .
4. 在感兴趣的BlueConfig (BC) 中注释掉RunMode字段，Circuit GLIA部分，Projection NeuroGlia部分以及Projection GlioVascular部分。
5. 返回 MultiscaleRun 仓库并运行 blueconfig convert-to-sonata /gpfs/bbp.cscs.ch/project/proj62/Circuits/O1/20190912_spines/sonata/circuit_config.json ngv.json user.target BlueConfig。第一个参数，即 circuit_config，应指向现有的 SONATA 电路配置文件，可以通过搜索 BlueConfig 中定义的 CircuitPath 字段所在的文件夹找到。第二个参数是用于从 BlueConfig 创建的 SONATA 模拟配置文件的名称。第三个参数是现有 SONATA 节点集文件的路径，第四个参数是我们想要转换的 BlueConfig。
6. 现在可以从 Jupyter notebook 使用 ngv.json 进行可视化。

使用 ARM MAP 分析 MultiscaleRun 脚本

1. 在环境中加载 ARM MAP：module load arm-forge
2. 运行模拟：map --profile --output OUT.map srun [...] multiscale-run compute [/path/to/my-sim]
3. 使用 Arm Forge 客户端（本地）打开 OUT.map

有关在 BB5 上使用 ARM MAP 的更多信息，请参阅此页面。

变更日志

0.8.2 - 2024-08-27

项目治理

• 在 GitHub 上开源发布https://github.com/BlueBrain/MultiscaleRun
• 在 https://multiscalerun.rtfd.io 上发布文档
• 将一些 GitLab CI/CD 任务移至 GitHub 工作流。

错误修复

• virtualenv 在从 Python 环境本身调用时没有正确设置 HOC_LIBRARY_PATH。

0.8.1 - 2024-07-03

错误修复

• edit-mod-files 不再工作，因为 neurodamus 改变了 mod 文件夹的位置。已更新。
• edit-mod-files 提供了错误的建议，因为我们现在应该使用 build_neurodamus.sh mod --only-neuron。

0.8 - 2024-06-04

主要更改

• 配置文件中的 connections 部分已更改
  • 您可以指定连接的位置以及是否要将连接结果（vals）也写入源模拟器。
  • 矩阵现在是 op 操作的一部分，可以在代码的任何地方使用。
  • 每个连接都需要一个 dest_simulator 键，因为 connect_to 键不再指定目标模拟器是哪个模拟器。
  • 以前的 simulation_config.json 文件必须进行适配，因为向后兼容性不可行。然而，如果将新模板与旧版本（v 0.7，config_format：2）的配置文件进行比较，则更改应该很小且易于理解。
• 在 check 和 compute 操作期间对文件 simulation_config.json 中的 MultiscaleRun 配置进行彻底验证。

内部更改

• 改进类 multiscale_run.MsrConfig 的内存使用
• 在根目录中添加 update_currents.sh 以进行临时存储。我们仍需要弄清楚将其放在哪里，或者是否想保留它。Sofia Farina 和 Alexis Arnaudon 对此文件了解更多信息。

0.7 - 2024-04-10

主要更改

重构配置对象和配置文件

• 配置文件 msr_config.json 已不再存在。所有 MultiscaleRun 配置都已合并到 simulation_config.json 中的新根部分：multiscale_run。这还不是 SONATA。配置在同一个文件中，但 Neurodamus 并不知道它。[BBPP40-455]。
• 配置与 0.6 版本相比发生了重大变化。现在 文档 有一个专门的页面来解释如何使用它。
• 代谢中的所有 magic numbers 都已移动到配置或删除。因此，模拟行为发生了变化。目前，神经元发生 ATP 缺乏，导致模拟在一段时间后中断。这需要将在未来版本中包含的研究。

重构代谢

• 所有在各个模拟器之间用作粘合剂的 魔数 都已被移至配置文件（simulation_config.json）或删除。
• 现在可以在配置文件中更改代谢时间步之前的值检查。例如，现在可以说如果神经元中的 ATP 低于 0.25，则应将其从模拟中踢出，并且模拟需要继续进行，而不包括它。有关如何操作的更多信息，请参阅配置文档。
• 代谢模型和代谢对象不再与固定数字相关联。因此，如果您想更改模型，只需更改配置文件即可。

模拟器之间连接的重构

• 现在可以从配置中程序化地更改模拟器之间的连接。在某个模拟器（称为 目标模拟器）执行 advance 操作后，连接管理器会遍历其连接，选择 源模拟器 并执行连接。目前有 3 种类型的连接
  • sum 在目标模拟器中将 源 和 目标 的值相加。
  • set 将 源 中的值设置到 目标。
  • merge 使用公式合并两个不一致的值 $V_{\text{source}}$ 和 $V_{\text{destination}}$：$V_{\text{source}} + V_{\text{destination}} - V_{n-1} = V_n$。然后将 $V_n$ 设置在 源 和 目标 中。这是唯一一种会更改 源 的连接类型。请注意，交换 源 和 目标 并不完全等价，因为同步是在 目标 执行 advance 之后进行的。

报告的重构

• 报告结构已显着更改（主要简化并改进）。然而，这些更改大多在幕后进行，除了配置文件中的更改。请考虑阅读文档中适当的章节，以了解更多关于 MultiscaleRun 报告的信息。

微小更改

• 为配置文件添加了文档。
• 在代码中添加了 docstrings。
• bf -> bloodflow 关键字更改以简化未来的开发 [BBPP40-440]。
• 为代码中的函数签名添加了类型建议。
• 为 sphinx 文档格式化 docstrings。
• 更新 postproc 以处理新的配置。
• 重构 Python import 语句和 MPI 库的初始化，以解决在调用 MPI_Finalize 时可能出现的挂起问题。
• 在持续集成过程中添加代码的静态分析。

错误修复

• 修复 pytest CI 中的错误，即使某些测试失败，它也能通过。
• 修复使用 MPI 时抛出错误时挂起的模拟 [BBPP40-427]。

0.6 - 2024-03-04

• virtualenv 命令
  • 改进：现在如果需要，该命令会安装 spack pkg。不再需要手动运行 spack 命令。[!104]
  • 修复从 BB5 模块 py-multiscale-run 加载 MultiscaleRun 时的问题。[BBPP40-430]
• edit-mod-file 命令：如果需要，则加载 intel 编译器模块 (!104)
• 改进 Python API 的文档。

0.5.1 - 2024-02-07

• 修复：使用 julia create 初始化时未指向正确的位置。

0.5 - 2024-01-29

• 改进 README。
• msr_config.json 现在是一个模板。为 bbp 工作流程做准备。
• base_path 现在在主配置文件中指定。这是一个破坏性更改。将以下字段添加到您的 msr_config.json 文件中： "base_path": "."
• ndam 现在强制使用 RoundRobin。

0.4 - 2024-01-19

• 新命令
  • edit-mod-files：克隆 Neurodamus mod 文件库以进行本地编辑。
  • virtualenv：创建 Python 虚拟环境，以简化 MultiscaleRun Python 包的开发。
• 修复由于敏感的 MPI 初始化而可能导致的程序挂起。
• 改进 README。
• 添加了关于 spack 环境 的章节
• 将 ratV10 的标准网格细化程度提高，以避免出现没有四面体的等级（omega_h 无法处理它们）
• 与 bbp 工作流程对齐

0.3 - 2024-01-10

• 新的 后处理 命令根据仿真结果创建 HTML 报告。用法：multiscale-run post-processing [sim-path]。使用 multiscale-run post-processing -h 获取更多信息。
• init 命令
  • 新增 --no-check 选项以跳过持续几分钟的 Julia 环境测试
  • 在 msr_config.json 中添加了新的键
    • config_format：一个整数，表示该文件结构的版本
    • msr_version：一个字符串，表示创建此配置的 MultiscaleRun 版本
• compute 命令：现在在仿真结束时创建 Neurodamus 成功文件
• 关于使用先前版本的 MultiscaleRun 创建的仿真的兼容性说明
  • 将目录 julia_environment 重命名为 .julia_environment
  • 无法使用环境变量覆盖 JSON 配置键。
• BB5 上的 GitLab CI 现在依赖于 spack

0.2 - 2023-12-14

• 重构报告 [BBPP40-402, BBPP40-407, BBPP40-410, BBPP40-411, BBPP40-415]

0.1 - 2023-11-30

作为 Python 包发布的代码的第一个版本

作者

波琳娜·希奇科娃、亚历山德罗·卡塔比亚尼、克里斯托斯·科塔洛斯和特里斯坦·卡雷尔

资助和致谢

本软件的开发得到了瑞士联邦理工学院洛桑联邦理工学院（EPFL）蓝脑项目的资助，该项目得到了瑞士政府 ETH 委员会的支持。

版权 (c) 2023-2024 蓝脑项目/EPFL