Mesh Generation Skill | Agent Skills

Mesh Generation

Goal

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

Requirements

Python 3.10+
No external dependencies (uses stdlib)

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 |

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

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 |

Script Outputs (JSON Fields)

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).

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

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:

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.

Pre-Mesh Checklist

[ ] Define target resolution per feature/interface
[ ] Ensure dx meets stability constraints (see numerical-stability)
[ ] Check aspect ratio < limit (typically 5:1)
[ ] Check skewness < threshold (typically 0.8)
[ ] Validate mesh convergence with refinement study

CLI Examples

# 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

Error Handling

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

| 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 |

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 |

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.

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 |

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.

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. |

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

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

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

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

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).

References

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

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

Agent Skills: Mesh Generation

Install this agent skill to your local

Skill Files