Mesh Generation

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 | must be a finite positive number, got ... | dx/dy/dz not finite or not positive | Use a finite positive value | | 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HeshamFS
• Source: HeshamFS/materials-simulation-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.