genesis-flyingfocus

genesis-flyingfocus 是面向企业内部使用的 GENESIS 改编版，用于 CPU/MPI 环境下的飞行焦点激光波荡器（flying-focus laser undulator）仿真、验证和 数据分析。仓库保留完整程序源码、构建配置、模拟示例以及配套数据处理脚本。

当前内部候选版的主要支持面是 Linux x86-64 CPU/MPI。源码中仍保留历史 CUDA 路径，但飞行焦点物理模型当前只允许 CPU 路径；不要把 CUDA 代码存在 误解为该模型已经通过 GPU 发布验收。

仓库内容

README.md                         本说明
genesis-flyingfocus/              完整改编版程序
  include/                        C++ 头文件
  src/                            CPU、MPI 与保留的 CUDA 源码
  examples/                       完整模拟示例
  tools/ramsey_ff_reproduction/   飞行焦点运行与数据处理脚本
  docs/使用指南.md              详细中文使用文档

模拟示例集中在 genesis-flyingfocus/examples/， 其中 RamseyLDFEL/ 是飞行焦点参数模板；数据生成、HDF5 分析、收敛检查和绘图 脚本集中在 genesis-flyingfocus/tools/ramsey_ff_reproduction/。

主要改动

相较于常规磁波荡器模型，本改编版增加了：

• plane_wave、ideal_flying_focus_fgb 和 conventional_gaussian 三种激光 波荡器模型；
• 随切片坐标和焦点速度变化的激光振幅、相位与移动焦点坐标；
• 横向有质动力项以及可选的轴对称横向空间电荷；
• 激光相位、归一化和相互作用窗口控制；
• 用于证明实际启用模型和参数的 HDF5 元数据；
• 有界的小规模验证、长程仿真、收敛检查和结果溯源脚本。

典型的 &track 控制项包括：

laser_undulator = true
laser_undulator_model = plane_wave | ideal_flying_focus_fgb | conventional_gaussian
laser_lambda_laser = 10e-6
laser_a0 = 0.35
laser_waist = 37.5e-6
laser_focus_center = ...
laser_interaction_length = ...
laser_focal_range = ...
laser_vf = 299792458.0
laser_conventional_zr = ...
laser_s_reference = ...
laser_phase_model = none | gaussian | chromatic | auto
laser_chromatic_bandwidth = 0
laser_transverse_space_charge = true | false

CPU/MPI 构建

依赖包括支持 C++17 的编译器、CMake、MPI、并行 HDF5，以及 CPU FFT 路径所需 的 FFTW。建议先运行不会安装软件的依赖检查：

cd genesis-flyingfocus
bash tools/release/check_dependencies.sh
cmake --preset cpu-release
cmake --build --preset cpu-release --parallel 8
./build/cpu-release/genesis4 --version

也可以使用直接配置方式：

cmake -S genesis-flyingfocus -B genesis-flyingfocus/build-cpu -DUSE_CUDA=OFF
cmake --build genesis-flyingfocus/build-cpu --parallel 8

模拟示例

仓库包含稳态、dump、时变、HGHG/EEHG 和 Ramsey 飞行焦点示例。最小的 飞行焦点模板位于：

genesis-flyingfocus/examples/RamseyLDFEL/ramsey_flying_focus.in
genesis-flyingfocus/examples/RamseyLDFEL/ramsey_flying_focus.lat

输入文件中的 lattice 路径按当前工作目录解析，因此请进入示例目录后运行：

cd genesis-flyingfocus/examples/RamseyLDFEL
mpirun -np 1 ../../build/cpu-release/genesis4 ramsey_flying_focus.in

该示例只是参数模板，不等同于已完成收敛认证的论文复现。

飞行焦点验证与数据处理

先执行有界验证流程：

bash genesis-flyingfocus/tools/ramsey_ff_reproduction/run_after_pull.sh validate

主要数据处理入口如下：

ramsey_ff_campaign_generate.py    生成仿真案例与 manifest
ramsey_ff_campaign_run.sh         按 manifest 运行案例并记录 ledger
ramsey_ff_campaign_analyze.py     读取 HDF5、生成 CSV、图和 provenance
ramsey_ff_convergence_check.py    检查收敛性
ramsey_ff_input_contract_check.py 检查输入契约
ramsey_ff_longflow_acceptance.py  检查长程输出完整性和数值门槛

完整生产或论文规模流程耗时很长，并带有显式授权开关和停止条件；首次使用请 先完成短验证，不要直接启动 full 或 paper 模式。历史独立复核记录显示： 确定性长程、前缀细化以及预声明三种子 SASE v016（26/26）均通过对应冻结门槛； 但 v016 原始 HDF5 不随 Git 分发，本次也没有重跑。三种子结果不等于充分统计 收敛，且三个功率峰均位于 12.5 mm 终点，不能据此宣告稳定饱和位置或完成原论文 最终性能复现。

输出与版本控制

构建目录、HDF5 输出、图片、benchmark、测试和发布工程历史由 .gitignore 排除，不会进入企业远程仓库。运行脚本默认把结果写到本地 runs/ 版本目录；请保留输入、commit、seed、日志、manifest 和分析结果，避免 覆盖旧证据。

详细中文文档

详细中文使用指南已生成：

genesis-flyingfocus/docs/使用指南.md

新用户可凭该指南完成依赖检查、CPU/MPI 构建、版本检查、RamseyLDFEL 示例以及 有界验证流程。