radiasoft/beamsim-jupyter

radiasoft/beamsim 镜像文档

镜像概述与主要用途

radiasoft/beamsim镜像是由Radiasoft开发的专用光束模拟环境，集成Jupyter Notebook/Lab交互界面，专为JupyterHub平台部署设计。该镜像将光束模拟工具链与Jupyter生态深度整合，提供开箱即用的光束物理模拟、数据分析及可视化能力，简化多用户协作场景下的环境配置流程。

主要用途：

• 为科研人员提供JupyterHub环境下的光束模拟集成开发平台
• 支持粒子光束传输、聚焦等物理过程的数值模拟与结果分析
• 作为JupyterHub用户环境镜像，实现多用户资源集中管理与任务调度

核心功能与特性

核心功能

1. Jupyter环境集成：内置Jupyter Notebook及可选Jupyter Lab，支持交互式代码开发与文档化计算
2. 光束模拟工具集：包含beamsim核心模拟库，支持光束物理过程的建模与仿真计算
3. JupyterHub兼容：符合JupyterHub镜像规范，可被DockerSpawner等组件直接调用管理

特性

• 预配置依赖：已预装NumPy、SciPy等科学计算库及可视化工具，无需手动配置环境
• 轻量级优化：精简镜像体积，提升部署启动速度，适合大规模集群环境
• 用户隔离机制：在JupyterHub中支持多用户独立运行，确保计算资源与数据安全隔离

使用场景与适用范围

使用场景

1. 科研机构模拟研究：加速器实验室、粒子物理研究中心用于光束传输特性模拟
2. 高校教学实验：物理、工程专业课程中作为学生进行光束模拟实验的标准化环境
3. 团队协作项目：科研团队共享模拟环境，协同进行数据处理与结果分析

适用范围

• 用户群体：光束物理研究员、加速器工程师、相关专业师生及科研团队
• 硬件要求：支持Docker的x86_64架构服务器（推荐配备GPU以提升模拟计算性能）
• 软件环境：需配合JupyterHub 1.0+版本，支持Docker Swarm/Kubernetes等容器编排平台

使用方法与配置说明

独立测试运行

通过以下命令可直接启动镜像进行功能测试：

bash
docker run -d -p 8888:8888 --name beamsim-test docker.xuanyuan.run/radiasoft/beamsim

获取Jupyter访问链接（含安全token）：

bash
docker logs beamsim-test

在浏览器访问 http://<主机IP>:8888，输入日志中的token即可进入Jupyter界面。

JupyterHub集成部署

前提条件

• 已部署JupyterHub服务（推荐使用DockerSpawner作为容器调度器）
• 服务器可访问Docker镜像仓库（或已本地拉取radiasoft/beamsim镜像）

配置步骤

1. 编辑JupyterHub配置文件（jupyterhub_config.py）：

python
c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'
c.DockerSpawner.image = 'radiasoft/beamsim'
# 配置用户数据持久化（可选）
c.DockerSpawner.volumes = {'/data/jupyterhub/{username}': '/home/jovyan/work'}
# 设置资源限制（可选）
c.DockerSpawner.mem_limit = '4G'
c.DockerSpawner.cpu_limit = 2

2. 重启JupyterHub服务使配置生效：

bash
systemctl restart jupyterhub  # 系统服务方式部署时
# 或
docker restart jupyterhub     # Docker容器方式部署时

3. 用户通过JupyterHub登录后，系统自动分配该镜像容器，直接进入光束模拟工作环境。

环境变量配置

支持通过环境变量调整服务参数，常用配置项：

示例：指定访问token并启用Jupyter Lab：

bash
docker run -d -p 8888:8888 \
  -e JUPYTER_TOKEN=my_secure_token_123 \
  -e JUPYTER_ENABLE_LAB=yes \
  docker.xuanyuan.run/radiasoft/beamsim

注意事项

1. 镜像默认使用非root用户（UID=1000）运行，挂载宿主机目录时需确保权限匹配
2. 生产环境建议配置数据卷持久化用户工作目录，避免容器重启导致数据丢失
3. 大规模部署时应配置资源限制（CPU/内存/GPU），防止单用户过度占用集群资源
4. 光束模拟具体功能使用方法请参考镜像内文档（通常位于/opt/beamsim/docs目录）