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

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

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"]["..."].

meshquality.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 highskewness is never flagged. Cell elongation is reported separately via aspectratio and the redundant convenience field sizeanisotropy (= 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 ``

1. Verify interface is resolved: dx = 5 μm, interface width = 10 μm → 2 points per interface width.
2. 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.

Interpretation Guidance

Aspect Ratio

Skewness

Skewness is the angular deviation from the ideal cell shape (max(|90° - θi|) / 90° for quads/hexes — see references/qualitymetrics.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.

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

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 aspectratio and qualityflags from meshquality.py --json; confirmed highaspect_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

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 sizeanisotropy, made meshquality.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