mesh-generation

网格生成

目标

为 PDE 仿真提供一致的工作流，以选择网格分辨率并检查网格质量。

要求

• Python 3.10+
• 无外部依赖（使用标准库）

需要收集的输入

输入	描述	示例
域尺寸	物理尺寸	1.0 × 1.0 m
特征尺寸	需要解析的最小特征	0.01 m
每个特征的点数	分辨率要求	10 points
长宽比限制	最大 dx/dy 比率	5:1
质量阈值	偏斜度限制	< 0.8

决策指南

分辨率选择

What is the smallest feature size?
├── Interface width → dx ≤ width / 5
├── Boundary layer → dx ≤ layer_thickness / 10
├── Wave length → dx ≤ lambda / 20
└── Diffusion length → dx ≤ sqrt(D × dt) / 2

网格类型选择

问题	推荐网格
几何简单且均匀	结构化笛卡尔网格
几何复杂	非结构化三角形/四面体网格
边界层	混合网格（壁面附近采用结构化网格）
自适应细化	四叉树/八叉树或 AMR

脚本输出（JSON 字段）

所有脚本都会输出一个顶层对象，其中包含 inputs（回显的 CLI 值）和 results（下表所列的计算字段）。通过 result["results"]["..."] 进行索引。

脚本	results 字段
scripts/grid_sizing.py	dx、counts（各维度的单元数列表，长度 == dims）、notes
scripts/mesh_quality.py	aspect_ratio、skewness、size_anisotropy、quality_flags、dims、notes

mesh_quality.py 描述的是仅由边长间距定义的轴对齐（正交笛卡尔）单元。对于这类单元，每个内角均为 90°，因此真实的角度 skewness 始终为 0.0，且不会标记 high_skewness。 单元拉伸程度通过 aspect_ratio 单独报告，冗余的便捷字段 size_anisotropy 则表示（= 1 - 1/aspect_ratio）。

工作流

1. 估算分辨率 - 根据物理尺度确定
2. 计算网格尺寸 - 运行 scripts/grid_sizing.py
3. 检查质量指标 - 运行 scripts/mesh_quality.py
4. 按需调整 - 修正长宽比，降低偏斜度
5. 验证 - 进行网格收敛性研究

对话式工作流示例

用户：我需要为界面宽度为 10 μm 的相场仿真，对一个 1mm × 1mm 的区域划分网格。

Agent 工作流：

1. 计算网格尺寸：

   python3 scripts/grid_sizing.py --length 0.001 --resolution 200 --json
   

2. 验证界面是否得到解析：dx = 5 μm，界面宽度 = 10 μm → 每个界面宽度有 2 个点。
3. 建议：增加到 500 个点（dx = 2 μm），使界面宽度内有 5 个点。

网格划分前检查清单

• 为每个特征/界面设定目标分辨率
• 确保 dx 满足稳定性约束（参见 numerical-stability）
• 检查长宽比是否小于限制值（通常为 5:1）
• 检查偏斜度是否小于阈值（通常为 0.8）
• 通过细化研究验证网格收敛性

CLI 示例

# Compute grid sizing for 1D domain
python3 scripts/grid_sizing.py --length 1.0 --resolution 200 --json

# Check mesh quality (3D cell)
python3 scripts/mesh_quality.py --dx 1.0 --dy 0.5 --dz 0.5 --json

# High aspect ratio check (2D cell; --dz omitted is treated as 2D)
python3 scripts/mesh_quality.py --dx 1.0 --dy 0.1 --json

错误处理

所有验证错误都会写入 stderr，脚本以代码 2 退出。

错误消息	原因	解决方法
length must be positive, got ...	域尺寸非正数	使用正值
resolution must be positive, got ...	分辨率非正数（resolution=1 是有效的单单元网格）	使用正整数
dims must be one of (1, 2, 3), got ...	维度数不受支持	使用 1、2 或 3
<name> must be a finite positive number, got ...	dx/dy/dz 不是有限正数	使用有限正值
<name> exceeds maximum (...), got ...	输入超出资源耗尽上限	使用较小的值

解读指南

长宽比

长宽比	质量	影响
1:1	极佳	精度最优
1:1 - 3:1	良好	可以接受
3:1 - 5:1	一般	可能影响精度
> 5:1	较差	可能导致求解器问题

偏斜度

偏斜度是相对于理想单元形状的角度偏差 （四边形／六面体为 max(|90° - θ_i|) / 90°，详见 references/quality_metrics.md）。 mesh_quality.py 根据沿坐标轴对齐的边长间距进行计算，这些间距描述的是内部角度均为 90° 的正交笛卡尔单元；因此，对于这类单元，它始终会报告 skewness = 0.0。以下阈值适用于根据真实单元角点几何结构（例如非结构网格）得出的实际偏斜度值，而不适用于根据 dx/dy/dz 间距得出的值。

偏斜度	质量	影响
0 - 0.25	极佳	最优
0.25 - 0.50	良好	可接受
0.50 - 0.80	一般	可能影响精度
> 0.80	较差	很可能出现问题

注意：单元拉长不等于偏斜。各向异性但正交的单元 （例如沿壁面对齐的边界层单元）具有较高的 aspect_ratio / size_anisotropy，但偏斜度为零，通常完全可以接受。

分辨率指南

应用场景	每个特征的点数
相场界面	5-10
边界层	10-20
激波	3-5（使用捕捉方法时）
波传播	每个波长 10-20
平滑梯度	5-10

验证清单

• 记录了 grid_sizing.py --json 输出的 dx 和 counts，并确认最小物理特征获得了足够的点数（界面 ≥5×dx，边界层 ≥10×dx，波长 ≥20×dx，详见上文“分辨率选择”）。
• 对于各向异性区域，针对不同的边长分别运行了一次 grid_sizing.py（或按坐标轴应用 --dx）——未将根据单个 --length 得出的计数应用于长度不等的边。
• 检查了 notes 字段中是否包含 "Grid does not fully cover length"，并在信任 counts 之前解决了任何覆盖不全警告。
• 记录了 mesh_quality.py --json 输出的 aspect_ratio 和 quality_flags；确认不存在 high_aspect_ratio，或者拉长是有意且符合物理方向的（例如沿壁面对齐、壁面方向 AR≤100 的边界层单元）。
• 确认报告的 skewness = 0.0 是符合预期的正交笛卡尔网格结果，并非测得的质量合格结果——对于非结构／非正交单元，已根据单元角点几何结构计算真实的基于角度的偏斜度，并确认其低于 0.8 的阈值。
• 确认 dx 也满足求解器的稳定性约束（与 numerical-stability 交叉核对），再确定分辨率。
• 进行了网格收敛性研究（≥3 个逐步加密的网格），并确认关注量单调／渐近变化后，才判定网格足够。

常见误区与错误理由

看似省事的做法	为什么不对 / 应该怎么做
“skewness 返回了 0.0，所以网格质量没问题。”	对于轴对齐的间距，mesh_quality.py 总是返回 skewness = 0.0——这是正交单元的定义属性，并非测量结果。真实的偏斜度需要从非结构网格中获取单元角点角度；不要把 0.0 当作质量检查通过。
“两个网格算出的结果几乎相同，所以网格已经收敛。”	两个网格无法确定观测阶数或渐近范围。请使用 ≥3 个逐步加密的网格，并确认关注量正在收敛，再将任何结果称为与网格无关。
“aspect_ratio 很高，被标记出来了，所以这个单元很差。”	拉长不等于偏斜。沿壁面对齐的边界层单元，即使 AR 高达约 100，只要与流场/场量对齐，仍可接受；应检查 size_anisotropy 和物理情况，而不只是 high_aspect_ratio 标记。
“我会设置一个 --length，然后把 counts 用于所有轴。”	grid_sizing.py 每次调用都采用各向同性设置——它会将推导出的单个计数应用于每个维度。对于长度不等的边，这会导致某些轴分辨率过高或不足；请对每条边分别运行，或为每个轴提供 --dx。
“dx = length/resolution 能分辨我的特征，因为 resolution 很大。”	每个区域的点数不等于每个特征的点数。即使全局 dx 很小，薄界面/薄层上的单元数量仍可能不足；请根据分辨率指南检查 feature_size / dx（界面为 5-10，边界层为 10-20）。
“网格已经足够精细，所以我可以忽略时间步长。”	网格分辨率与时间稳定性相互耦合：缩小 dx 会收紧显式 CFL/扩散限制。若加密后的网格违反求解器的稳定性约束，计算就会发散——每次加密后都要重新检查 dt 是否满足数值稳定性要求。

安全性

输入验证

• 所有输入（length、resolution、dx、dy、dz）都会验证是否为有限正数，并设有上限以防止资源耗尽
• dims 限制为 {1, 2, 3}
• argparse 类型参数会在命令行界面处拒绝非数值输入，避免其进入后续处理

文件访问

• 脚本不会读取外部文件；所有输入均通过命令行参数提供
• 脚本只向 stdout 写入内容（JSON 输出）；除非 Agent 明确使用 Write 工具，否则不会创建文件

工具限制

• Read：用于检查脚本源代码、参考资料和用户配置文件
• Write：用于保存网格尺寸建议或网格质量报告；写入范围限定在用户的工作目录内
• Grep/Glob：用于定位相关文件和搜索参考资料
• 该技能的 allowed-tools 不包含 Bash，以防 Agent 在处理用户提供的输入时执行任意命令

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用都使用显式参数列表（不使用 shell=True）
• 由于工具范围缩减（不包含 Bash），Agent 应使用 Read 和 Write 来准备输入并捕获输出，而不是根据用户文本构造 shell 命令
• 所有输出均为确定性的 JSON，不包含可由 shell 解释的内容

限制

• 仅支持 2D/3D：不生成非结构网格
• 质量指标：仅根据轴对齐的间距计算纵横比和尺寸各向异性；对于这些正交单元，偏斜度报告为 0（真正的角度偏斜度需要真实的单元角点几何信息）
• 不生成网格：仅提供尺寸建议
• 每次调用均采用各向同性设置：grid_sizing.py 接受单个 --length，并将得到的计数应用于每个维度。对于各向异性区域（例如 10 cm × 5 cm），请针对每个不同的边长分别运行一次，或根据物理情况计算 dx 并将其应用于各个轴（例如，--length 0.10 --dx 5e-5，然后是 --length 0.05 --dx 5e-5）。

参考资料

• references/mesh_types.md - 结构化与非结构化网格
• references/quality_metrics.md - 长宽比／偏斜度阈值

版本历史

• v1.2.0（2026-06-23）：修正偏斜度的科学定义（正交单元现在报告偏斜度为 0），新增 size_anisotropy，使 mesh_quality.py --dz 成为可选参数（适用于 2D 单元），修复基于分辨率计算数量时 grid_sizing 的差一错误，补充 dx 覆盖说明，修正输出和错误处理文档
• v1.1.0（2024-12-24）：完善文档、决策指南和示例
• v1.0.0：首次发布，包含 2 个网格质量脚本