performance-profiling

性能分析

目标

提供用于分析模拟性能、识别瓶颈并为计算材料科学模拟推荐优化策略的工具。

要求

• Python 3.10+
• 无外部依赖（仅使用 Python 标准库）
• 支持 Linux、macOS 和 Windows

需要收集的输入

运行分析脚本前，请向用户收集：

输入	描述	示例
模拟日志	包含计时信息的日志文件	simulation.log
扩展数据	包含多次运行性能数据的 JSON	scaling_data.json
模拟参数	包含网格、场和求解器配置的 JSON	params.json
可用内存	系统内存，以 GB 为单位（可选）	16.0

决策指南

何时使用各个脚本

Need to identify slow phases?
├── YES → Use timing_analyzer.py
│         └── Parse simulation logs for timing data
│
Need to understand parallel performance?
├── YES → Use scaling_analyzer.py
│         └── Analyze strong or weak scaling efficiency
│
Need to estimate memory requirements?
├── YES → Use memory_profiler.py
│         └── Estimate memory from problem parameters
│
Need optimization recommendations?
└── YES → Use bottleneck_detector.py
          └── Combine analyses and get actionable advice

选择分析阈值

指标	良好	可接受	较差
阶段占比	<30%	30-50%	>50%
并行效率	>0.80	0.70-0.80	<0.70
内存使用率	<60%	60-80%	>80%

脚本输出（JSON 字段）

所有脚本都会将有效载荷封装在一个包含两个键的顶层对象中：inputs 和 results。下列字段位于 results 下。

脚本	关键输出（位于 results 下）
timing_analyzer.py	results.phases、results.slowest_phase、results.total_time
scaling_analyzer.py	results.results、results.efficiency_threshold_processors、results.average_efficiency、results.baseline
memory_profiler.py	results.total_memory_gb、results.per_process_gb、results.field_memory_gb、results.solver_workspace_gb、results.matrix_storage_gb、results.warnings
bottleneck_detector.py	results.bottlenecks、results.recommendations

工作流

完整分析工作流

1. 分析计时：从模拟日志中分析
2. 分析扩展情况：从多次运行数据中分析（如果有）
3. 分析内存：根据模拟参数分析
4. 检测瓶颈并获取建议
5. 根据建议实施优化
6. 重新分析以验证改进效果

快速分析（仅计时）

1. 对模拟日志运行计时分析器
2. 识别占主导地位的阶段（运行时间 >50%）
3. 针对占主导地位的阶段进行优化

CLI 示例

计时分析

# Basic timing analysis
python3 scripts/timing_analyzer.py \
    --log simulation.log \
    --json

# Custom timing pattern
python3 scripts/timing_analyzer.py \
    --log simulation.log \
    --pattern 'Step\s+(\w+)\s+took\s+([\d.]+)s' \
    --json

扩展分析

# Strong scaling (fixed problem size)
python3 scripts/scaling_analyzer.py \
    --data scaling_data.json \
    --type strong \
    --json

# Weak scaling (constant work per processor)
python3 scripts/scaling_analyzer.py \
    --data scaling_data.json \
    --type weak \
    --json

内存分析

# Estimate memory requirements
python3 scripts/memory_profiler.py \
    --params simulation_params.json \
    --available-gb 16.0 \
    --json

瓶颈检测

# Detect bottlenecks from timing only
python3 scripts/bottleneck_detector.py \
    --timing timing_results.json \
    --json

# Comprehensive analysis with all inputs
python3 scripts/bottleneck_detector.py \
    --timing timing_results.json \
    --scaling scaling_results.json \
    --memory memory_results.json \
    --json

对话工作流示例

用户：我的模拟运行时间太长了。你能帮我找出耗时的部分吗？

Agent 工作流：

1. 请求提供模拟日志文件
2. 运行计时分析器：

   python3 scripts/timing_analyzer.py --log simulation.log --json
   

3. 解读结果（检测器会标记占比超过 50% 的求解器/组装阶段，以及占比超过 30% 的 I/O 阶段；超过 70% 则属于高严重性）：
   • 如果求解器阶段占主导地位（>50%，超过 70% 时严重性较高）：建议调整预条件器
   • 如果组装阶段占主导地位（>50%）：建议使用缓存或向量化
   • 如果 I/O 阶段占主导地位（>30%）：建议降低输出频率
4. 如果用户有多次运行数据，则分析扩展情况：

   python3 scripts/scaling_analyzer.py --data scaling.json --type strong --json
   

5. 生成全面的建议：

   python3 scripts/bottleneck_detector.py --timing timing.json --scaling scaling.json --json
   

解读指南

计时分析

检测器按类型应用不同的占比阈值：求解器/组装/常规阶段占运行时间超过 50% 时会被标记；I/O 阶段超过 30% 时会被标记。任何被标记且占比超过 70% 的阶段都会报告为高严重性。

场景	含义	操作
求解器 >50%（超过 70% 时严重性较高）	求解器占主导地位	调整预条件器，检查容差
组装 >50%	组装占主导地位	缓存矩阵、向量化、并行化
I/O >30%	I/O 占主导地位	降低频率，使用并行 I/O
均衡（低于阈值）	均衡良好	寻找算法改进机会

扩展性分析

效率	含义	操作
>0.80	扩展性极佳	继续扩展
0.70-0.80	扩展性良好	在更大规模下监控
0.50-0.70	扩展性较差	排查通信／负载均衡问题
<0.50	扩展性很差	减少处理器数量或重新设计

内存配置

使用量	含义	操作
<60% 可用	安全	无需操作
60-80% 可用	中等	监控并考虑优化
>80% 可用	较高	降低分辨率或增加处理器
>100% 可用	超出容量	必须缩小问题规模

估算遵循三项公式 Total = Field + Solver Workspace + Matrix Storage（参见 references/profiling_guide.md）。矩阵存储和求解器工作区取决于 solver.type：

• iterative（默认）：稀疏矩阵（默认 7 点模板，可通过 solver.stencil_nnz 覆盖）以及工作区向量。
• direct：稀疏矩阵乘以保守的填充因子（solver.fillin_factor，默认值为 10），以反映分解填充——对于相同网格，直接求解器估算的内存远多于迭代求解器。
• matrix-free：不组装矩阵；仅使用工作区向量。

此估算有意保持保守，避免在判断“是否能放入 RAM”时悄然低估。

错误处理

错误	原因	解决方法
Log file not found	路径无效	检查日志文件路径
No timing data found	模式不匹配	使用 --pattern 提供自定义模式
At least 2 runs required	数据不足	提供更多扩展性运行数据
Missing required parameters	参数不完整	在参数文件中添加网格和字段

按瓶颈类型划分的优化策略

求解器瓶颈

• 使用代数多重网格（AMG）预条件器
• 如果求解过度，则收紧求解器容差
• 对于小问题，考虑使用直接求解器
• 分析矩阵组装与求解时间

组装瓶颈

• 如果几何结构静态，则缓存单元矩阵
• 使用向量化组装例程
• 考虑使用无矩阵方法
• 使用着色法并行组装

I/O 瓶颈

• 降低输出频率
• 使用并行 I/O（HDF5、MPI-IO）
• 写入高速临时存储
• 压缩输出数据

扩展性瓶颈

• 排查通信开销
• 检查负载不均衡
• 减少同步点
• 使用异步通信
• 考虑混合 MPI+OpenMP

内存瓶颈

• 降低网格分辨率
• 使用迭代求解器（内存占用低于直接求解器）
• 启用外存计算
• 增加处理器数量
• 适当使用单精度

验证清单

在信任分析结果或采取建议措施之前，请记录以下具体证据：

• 确认 timing_analyzer.py 确实匹配到了条目——results.phases 非空，且 results.total_time > 0；如果使用了自定义 --pattern，并出现了 results.message/suggested_patterns，则应修正模式并重新运行（phases 列表为空会让模拟看起来像是运行得很快）。
• 交叉核对 phases[].percentage 的总和约为 100%，且已命名的阶段覆盖了墙钟时间——未计入的时间意味着日志行缺失，而不是运行均衡。
• 对于扩展性结论，使用 >=2 次运行，覆盖实际的处理器数量范围，并记录 scaling_analyzer.py 的 results.average_efficiency 和 results.efficiency_threshold_processors；确认 --type（强扩展还是弱扩展）与运行生成方式相符（总规模固定还是每个 rank 的工作量固定）。
• 记录 memory_profiler.py 给出的内存细分（field_memory_gb、solver_workspace_gb、matrix_storage_gb、total_memory_gb），并确认 solver.type（迭代 / 直接 / 矩阵自由）与实际求解器相符——直接求解会带来约 10 倍的填充因子，类型错误会导致“是否能装进 RAM？”这一判断不可靠。
• 检查 results.warnings，并将 total_memory_gb（以及 per_process_gb）与实际的 --available-gb 进行比较；超过 80% 应视为文档所述的“高”区间，而不是通过。
• 对于每条 bottleneck_detector.py 建议，确认其依据的 bottleneck（其 category、value 和 threshold）与实际提供的计时 / 扩展性 / 内存输入一致——建议仅反映通过 --timing/--scaling/--memory 传入的 JSON 文件。
• 实施优化后，重新运行相关分析器并记录优化前后的 value，以确认瓶颈确实有所改善（工作流中的重新分析步骤）。

常见误区与自我安慰

看似省事的做法	为什么不对 / 应该怎么做
“timing_analyzer.py 没有返回瓶颈，所以运行是均衡的。”	结果为空或偏低，往往是模式不匹配所致——phases 可能为空或不完整。得出“均衡”的结论前，请确认 total_time 与墙钟时间相符，且阶段百分比之和约为 100%。
“两次运行的扩展性不错，所以它具备扩展性。”	两个数据点只能得出平均效率，无法揭示效率从何处开始下降。增加处理器数量，并检查 efficiency_threshold_processors；同时确认使用了正确的 --type（强扩展还是弱扩展）。
“迭代求解还是直接求解只是一个标志；内存用量差不多。”	memory_profiler.py 会对 direct 应用保守的约 10 倍填充因子，并且对 matrix-free 不存储矩阵。设置错误的 solver.type 可能会低估一个数量级的 RAM 用量——请将其设为实际使用的求解器类型。
“总内存能装进 --available-gb，所以没问题。”	MPI 运行中相关的数值是 per_process_gb，应与每节点 / 每 rank 的 RAM 对比；而总内存用量超过 80% 就会触发警告。请检查每进程用量以及 warnings 列表，而不只是总量。
“I/O 占比不到 50%，所以 I/O 不是瓶颈。”	I/O 的标记阈值是较低的 30%，而不是 50%。占比为 30-50% 的 I/O 阶段确实是检测器会报告的瓶颈——请降低输出频率或使用并行 I/O。
“建议说要调整预条件器，所以问题出在求解器上。”	建议是否全面，取决于传入的 JSON。如果省略了 --scaling/--memory，这些瓶颈就不可见——请提供所有可用的分析结果，再相信优先级排序。

安全

输入验证

• 用户提供的 --pattern 正则表达式值会进行长度验证（最多 500 个字符），并拒绝包含易导致灾难性回溯（ReDoS）的结构
• 对缩放数据条目进行验证，确保时间值为有限值、处理器数量为整数，且运行次数不超过上限（最多 10,000 次）
• available_gb 会验证为正的有限数值；网格维度和场参数会验证为正整数
• --type（缩放类型）会根据固定的允许列表（strong、weak）进行验证
• 所有加载的 JSON 文件都必须以对象（dict）作为根元素

文件访问

• timing_analyzer.py 读取由 --log 指定的单个日志文件；日志文件大小上限为 500 MB，超过上限时会在解析前拒绝读取
• scaling_analyzer.py、memory_profiler.py 和 bottleneck_detector.py 读取大小上限为 100 MB 的 JSON 文件
• 从日志文件中提取的阶段名称会截断至 200 个字符，并剔除控制字符，以防提示词注入载荷传播到 Agent 上下文中
• 所有脚本均不会写入文件系统；所有输出都发送到 stdout

工具限制

• Read：用于检查脚本源代码、参考资料、模拟日志和结果文件
• Write：用于保存性能分析报告或优化建议；写入范围限定在用户的工作目录内
• Grep/Glob：用于查找日志文件、结果文件和参考资料
• 该技能的 allowed-tools 不包含 Bash，以防 Agent 在处理不可信的模拟日志或结果文件时执行任意命令

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用均使用显式参数列表（不使用 shell=True）
• 缩减工具范围（不包含 Bash），将 Agent 的操作限制为读写
• 阶段名称和诊断字符串在纳入输出前都会经过清理，以防注入

局限性

• 日志解析：依赖模式匹配；可能无法识别不常见的格式
• 缩放分析：至少需要 2 次运行才能获得有意义的结果
• 内存估算：属于近似估算；实际用量可能有所不同
• 建议：仅提供通用指导；可能需要根据特定领域进行调整

参考资料

• references/profiling_guide.md - 性能分析概念与结果解读
• references/optimization_strategies.md - 详细的优化方法

版本历史

权威且带日期的发布历史请参阅 CHANGELOG.md。