mesh-generation

Files (7)

• CHANGELOG.md
• SKILL.md
• evals.json · evals/
• mesh_types.md · references/
• quality_metrics.md · references/
• grid_sizing.py · scripts/
• mesh_quality.py · scripts/

SKILL.md (first lines)

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

From HeshamFS/materials-simulation-skills, Apache-2.0.

More from HeshamFS/materials-simulation-skills