mesh-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mesh Generation

网格生成

Goal

目标

Provide a consistent workflow for selecting mesh resolution and checking mesh quality for PDE simulations.

为PDE模拟提供一套统一的网格分辨率选择和网格质量检查工作流。

Requirements

要求

Python 3.10+
No external dependencies (uses stdlib)

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

Inputs to Gather

需要收集的输入

Input	Description	Example
Domain size	Physical dimensions	`1.0 × 1.0 m`
Feature size	Smallest feature to resolve	`0.01 m`
Points per feature	Resolution requirement	`10 points`
Aspect ratio limit	Maximum dx/dy ratio	`5:1`
Quality threshold	Skewness limit	`< 0.8`

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

Decision Guidance

决策指南

Resolution Selection

分辨率选择

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

最小特征尺寸是多少？
├── 界面宽度 → dx ≤ 宽度 / 5
├── 边界层 → dx ≤ 边界层厚度 / 10
├── 波长 → dx ≤ 波长 / 20
└── 扩散长度 → dx ≤ sqrt(D × dt) / 2

Mesh Type Selection

网格类型选择

Problem	Recommended Mesh
Simple geometry, uniform	Structured Cartesian
Complex geometry	Unstructured triangular/tetrahedral
Boundary layers	Hybrid (structured near walls)
Adaptive refinement	Quadtree/Octree or AMR

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

Script Outputs (JSON Fields)

脚本输出（JSON字段）

All scripts emit a top-level object with

inputs

(the echoed CLI values) and

results

(the computed fields below). Index as

result["results"]["..."]

Script	`results` Fields
`scripts/grid_sizing.py`	`dx` , `counts` (list of per-dimension cell counts, length == `dims` ), `notes`
`scripts/mesh_quality.py`	`aspect_ratio` , `skewness` , `size_anisotropy` , `quality_flags` , `dims` , `notes`

mesh_quality.py

describes axis-aligned (orthogonal Cartesian) cells defined purely by edge spacings. For such cells every interior angle is 90°, so the true angular

skewness

is always

0.0

and

high_skewness

is never flagged. Cell elongation is reported separately via

aspect_ratio

and the redundant convenience field

size_anisotropy

1 - 1/aspect_ratio

所有脚本都会输出一个顶层对象，包含

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

）单独报告。

Workflow

工作流

Estimate resolution - From physics scales
Compute grid sizing - Run
```
scripts/grid_sizing.py
```
Check quality metrics - Run
```
scripts/mesh_quality.py
```
Adjust if needed - Fix aspect ratios, reduce skewness
Validate - Mesh convergence study

估算分辨率 - 根据物理尺度计算
计算网格尺寸 - 运行
```
scripts/grid_sizing.py
```
检查质量指标 - 运行
```
scripts/mesh_quality.py
```
按需调整 - 修正纵横比，降低偏斜度
验证 - 开展网格收敛研究

Conversational Workflow Example

对话式工作流示例

User: I need to mesh a 1mm × 1mm domain for a phase-field simulation with interface width of 10 μm.

Agent workflow:

Compute grid sizing:

bash

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

Verify interface is resolved: dx = 5 μm, interface width = 10 μm → 2 points per interface width.
Recommend: Increase to 500 points (dx = 2 μm) for 5 points across interface.

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

Agent工作流:

计算网格尺寸:

bash

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

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

Pre-Mesh Checklist

网格划分前检查清单

CLI Examples

CLI示例

bash

undefined

bash

undefined

Compute grid sizing for 1D domain

计算1D域的网格尺寸

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

Check mesh quality (3D cell)

检查3D单元的网格质量

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)

高纵横比检查（2D单元；省略--dz视为2D）

python3 scripts/mesh_quality.py --dx 1.0 --dy 0.1 --json

undefined

python3 scripts/mesh_quality.py --dx 1.0 --dy 0.1 --json

undefined

Error Handling

错误处理

All validation errors are written to stderr and the script exits with code

Error message	Cause	Resolution
`length must be positive, got ...`	Non-positive domain size	Use a positive value
`resolution must be positive, got ...`	Non-positive resolution ( `resolution=1` is a valid single-cell mesh)	Use a positive integer
`dims must be one of (1, 2, 3), got ...`	Unsupported dimension count	Use `1` , `2` , or `3`
`<name> must be a finite positive number, got ...`	`dx` / `dy` / `dz` not finite or not positive	Use a finite positive value
`<name> exceeds maximum (...), got ...`	Input above the resource-exhaustion bound	Use a smaller value

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

退出。

错误信息	原因	解决方法
`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 ...`	输入超出资源耗尽上限	使用更小的值

Interpretation Guidance

解读指南

Aspect Ratio

纵横比

Aspect Ratio	Quality	Impact
1:1	Excellent	Optimal accuracy
1:1 - 3:1	Good	Acceptable
3:1 - 5:1	Fair	May affect accuracy
> 5:1	Poor	Solver issues likely

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

Skewness

偏斜度

Skewness is the angular deviation from the ideal cell shape (

max(|90° - θ_i|) / 90°

for quads/hexes — see

references/quality_metrics.md

mesh_quality.py

works from axis-aligned edge spacings, which describe orthogonal Cartesian cells whose interior angles are all exactly 90°; it therefore always reports

skewness = 0.0

for these cells. The thresholds below apply when a genuine skewness value is obtained from real cell-corner geometry (e.g. from an unstructured mesh), not from

dx/dy/dz

spacings.

Skewness	Quality	Impact
0 - 0.25	Excellent	Optimal
0.25 - 0.50	Good	Acceptable
0.50 - 0.80	Fair	May affect accuracy
> 0.80	Poor	Likely problems

Note: cell elongation is not skewness. An anisotropic but orthogonal cell (e.g. a wall-aligned boundary-layer cell) has high
aspect_ratio
/
size_anisotropy
but zero skewness, and is often perfectly acceptable.

偏斜度是与理想单元形状的角度偏差（对于四边形/六面体为

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
但偏斜度为零，通常是完全可接受的。

Resolution Guidelines

分辨率指南

Application	Points per Feature
Phase-field interface	5-10
Boundary layer	10-20
Shock	3-5 (with capturing)
Wave propagation	10-20 per wavelength
Smooth gradients	5-10

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

Verification checklist

验证检查清单

Recorded
```
dx
```
and
```
counts
```
from
```
grid_sizing.py --json
```
and confirmed the smallest physical feature gets enough points (interface ≥5×dx, boundary layer ≥10×dx, wavelength ≥20×dx per Resolution Selection above).
For an anisotropic domain, ran
```
grid_sizing.py
```
once per differing edge length (or applied
```
--dx
```
per axis) — did NOT apply a single
```
--length
```
-derived count to unequal edges.
Checked the
```
notes
```
field for "Grid does not fully cover length" and resolved any partial-coverage warning before trusting
```
counts
```
.
Logged
```
aspect_ratio
```
and
```
quality_flags
```
from
```
mesh_quality.py --json
```
; confirmed
```
high_aspect_ratio
```
is absent OR that the elongation is intentional and physics-aligned (e.g. wall-aligned boundary-layer cell with AR≤100 along the wall).
Confirmed the reported
```
skewness = 0.0
```
is the expected orthogonal-Cartesian result, NOT a measured quality pass — for unstructured/non-orthogonal cells, obtained a real angle-based skewness from cell-corner geometry and checked it against the <0.8 threshold.
Verified
```
dx
```
also satisfies the solver's stability constraint (cross-check with numerical-stability) before committing to the resolution.
Ran a mesh convergence study (≥3 successively refined grids) and confirmed the quantity of interest changes monotonically/asymptotically before declaring the mesh adequate.

记录
```
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个连续细化网格），确认关注的物理量单调收敛或渐近收敛后，再宣布网格足够。

Common pitfalls & rationalizations

常见误区与合理化借口

Tempting shortcut	Why it's wrong / what to do
" `skewness` came back 0.0, so the mesh quality is fine."	`mesh_quality.py` always returns `skewness = 0.0` for axis-aligned spacings — it is a definitional property of orthogonal cells, not a measurement. Real skewness needs cell-corner angles from an unstructured mesh; don't read 0.0 as a passing quality check.
"Two grids gave nearly the same answer, so the mesh is converged."	Two grids cannot establish the observed order or the asymptotic range. Use ≥3 successively refined grids and confirm the quantity of interest is converging before quoting any result as mesh-independent.
"High `aspect_ratio` was flagged, so the cell is bad."	Elongation is not skewness. A wall-aligned boundary-layer cell with AR up to ~100 is acceptable when aligned with the flow/field; check `size_anisotropy` and the physics, not just the `high_aspect_ratio` flag.
"I'll set one `--length` and reuse the `counts` for all axes."	`grid_sizing.py` is isotropic per call — it applies the single derived count to every dimension. For unequal edges this over/under-resolves axes; run it per edge length or supply `--dx` per axis.
" `dx = length/resolution` resolves my feature because resolution is large."	Points-per-domain is not points-per-feature. A fine global `dx` can still place too few cells across a thin interface/layer; check `feature_size / dx` against the Resolution Guidelines (5-10 for interfaces, 10-20 for boundary layers).
"The mesh is fine enough, so I can ignore the time step."	Mesh resolution and temporal stability are coupled: shrinking `dx` tightens explicit CFL/diffusion limits. A refined mesh that violates the solver's stability constraint diverges — re-check `dt` against numerical-stability after any refinement.

诱人的捷径	错误原因/正确做法
" `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` 能解析我的特征，因为分辨率很大。"	域内点数不是特征点数。全局精细的 `dx` 仍可能在薄界面/层上放置过少的单元；检查 `feature_size / dx` 是否符合分辨率指南（界面5-10，边界层10-20）。
"网格足够好了，所以我可以忽略时间步长。"	网格分辨率和时间稳定性是耦合的：减小 `dx` 会收紧显式CFL/扩散限制。违反求解器稳定性约束的细化网格会发散——任何细化后都要重新检查 `dt` 是否符合numerical-stability要求。

Security

安全性

Input Validation

输入验证

All inputs (
```
length
```
,
```
resolution
```
,
```
dx
```
,
```
dy
```
,
```
dz
```
) are validated as finite positive numbers with upper bounds to prevent resource exhaustion
```
dims
```
is restricted to
```
{1, 2, 3}
```
```
argparse
```
type parameters reject non-numeric input at the CLI boundary before any processing occurs

所有输入（
```
length
```
、
```
resolution
```
、
```
dx
```
、
```
dy
```
、
```
dz
```
）都被验证为有限的正数，并设置上限以防止资源耗尽
```
dims
```
被限制为
```
{1, 2, 3}
```
```
argparse
```
类型参数在CLI边界处拒绝非数值输入，再进行任何处理

File Access

文件访问

Scripts read no external files; all inputs are provided via CLI arguments
Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool

脚本不读取任何外部文件；所有输入都通过CLI参数提供
脚本仅向stdout写入（JSON输出）；除非Agent明确使用Write工具，否则不会创建文件

Tool Restrictions

工具限制

Read: Used to inspect script source, references, and user configuration files
Write: Used to save grid sizing results or mesh quality reports; writes are scoped to the user's working directory
Grep/Glob: Used to locate relevant files and search references
The skill's
```
allowed-tools
```
excludes
```
Bash
```
to prevent the agent from executing arbitrary commands when processing user-provided inputs

Read：用于检查脚本源码、参考文档和用户配置文件
Write：用于保存网格尺寸结果或网格质量报告；写入范围限于用户工作目录
Grep/Glob：用于定位相关文件和搜索参考内容
该技能的
```
allowed-tools
```
排除
```
Bash
```
，防止Agent处理用户输入时执行任意命令

Safety Measures

安全措施

No
```
eval()
```
,
```
exec()
```
, or dynamic code generation
All subprocess calls use explicit argument lists (no
```
shell=True
```
)
Reduced tool surface (no Bash) means the agent should use
```
Read
```
and
```
Write
```
to prepare inputs and capture outputs rather than constructing shell commands from user text
All output is deterministic JSON with no shell-interpretable content

不使用
```
eval()
```
、
```
exec()
```
或动态代码生成
所有子进程调用使用显式参数列表（不使用
```
shell=True
```
）
缩小工具范围（无Bash）意味着Agent应使用
```
Read
```
和
```
Write
```
准备输入和捕获输出，而非从用户文本构造shell命令
所有输出都是确定性JSON，不含可被shell解析的内容

Limitations

局限性

2D/3D only: No unstructured mesh generation
Quality metrics: Aspect ratio and size anisotropy from axis-aligned spacings only; skewness is reported as 0 for these orthogonal cells (true angular skewness requires real cell-corner geometry)
No mesh generation: Sizing recommendations only
Isotropic per call:
```
grid_sizing.py
```
takes a single
```
--length
```
and applies the resulting count to every dimension. For an anisotropic domain (e.g. 10 cm × 5 cm), run it once per differing edge length, or compute
```
dx
```
from physics and apply it per axis (e.g.
```
--length 0.10 --dx 5e-5
```
, then
```
--length 0.05 --dx 5e-5
```
).

仅支持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

参考文档

```
references/mesh_types.md
```
- Structured vs unstructured
```
references/quality_metrics.md
```
- Aspect ratio/skewness thresholds

```
references/mesh_types.md
```
- 结构化与非结构化网格对比
```
references/quality_metrics.md
```
- 纵横比/偏斜度阈值

Version History

版本历史

v1.2.0 (2026-06-23): Corrected skewness science (orthogonal cells now report skewness 0), added
```
size_anisotropy
```
, made
```
mesh_quality.py --dz
```
optional (2D cells), fixed grid_sizing off-by-one for resolution-derived counts, surfaced dx-override note, corrected output/error-handling docs
v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples
v1.0.0: Initial release with 2 mesh quality scripts

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个网格质量脚本