mesh-generation — Claude Code skill: grid sizing and mesh quality

---
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:
  last_deterministic_eval: "2026-10-20"
  agent_evaluation_status: "not_revalidated"
  author: HeshamFS
  version: "1.2.2"
  standards:
    - "ANSYS Fluent/ICEM equiangle skewness metric (max(|90-theta|)/90 for quads/hexes; (theta_max-60)/120 for triangles)"
    - "Knupp (2001), Algebraic mesh quality metrics (aspect ratio, Jacobian ratio, warpage)"
    - "Shewchuk (2002), What Is a Good Linear Finite Element? (triangle radius-ratio and minimum-angle quality, Delaunay)"
    - "Jasak (1996) / OpenFOAM finite-volume non-orthogonality correction"
    - "Roache (1998), Verification and Validation in Computational Science (grid/mesh convergence study)"
  security_tier: medium
  security_reviewed: true
  tested_with:
    - claude-code
  last_evaluated: "2026-06-24"
  eval_cases: 4
  last_reviewed: "2026-06-23"
---

# 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

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:
   ```bash
   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

```bash
# 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