mesh-generation

name	mesh-generation
description	Plan and evaluate mesh generation for numerical simulations — estimate grid resolution from physics scales (interface width, boundary layers, wavelengths), check aspect ratios and skewness against quality thresholds, choose between structured, unstructured, and adaptive mesh refinement strategies, and compute grid sizing for 1D/2D/3D domains. Use when setting up a new mesh, diagnosing poor solver convergence caused by mesh quality, deciding how many points to place across a phase-field interface or boundary layer, or preparing a mesh convergence study, even if the user only asks "what resolution do I need" or "why is my solver failing."
allowed-tools	Read, Write, Grep, Glob
metadata	{"author":"HeshamFS","version":"1.1.0","security_tier":"medium","security_reviewed":true,"tested_with":["claude-code","gemini-cli","vs-code-copilot"],"eval_cases":4,"last_reviewed":"2026-03-26"}

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)

Script	Key Outputs
scripts/grid_sizing.py	dx, nx, ny, nz, notes
scripts/mesh_quality.py	aspect_ratio, skewness, quality_flags

Workflow

1. Estimate resolution - From physics scales
2. Compute grid sizing - Run scripts/grid_sizing.py
3. Check quality metrics - Run scripts/mesh_quality.py
4. Adjust if needed - Fix aspect ratios, reduce skewness
5. 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:

1. Compute grid sizing:

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

2. Verify interface is resolved: dx = 5 μm, interface width = 10 μm → 2 points per interface width.
3. 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
python3 scripts/mesh_quality.py --dx 1.0 --dy 0.5 --dz 0.5 --json

# High aspect ratio check
python3 scripts/mesh_quality.py --dx 1.0 --dy 0.1 --json

Error Handling

Error	Cause	Resolution
length must be positive	Invalid domain size	Use positive value
resolution must be > 1	Insufficient points	Use at least 2
dx, dy must be positive	Invalid spacing	Use positive values

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

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

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: Basic aspect ratio and skewness only
• No mesh generation: Sizing recommendations only

References

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

Version History

• v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples
• v1.0.0: Initial release with 2 mesh quality scripts