matlab-solve-pde

# PDE Toolbox — Full FEA Workflow

End-to-end finite element analysis: geometry → model setup → solve → post-process. Uses the modern `femodel` workflow (R2025a+).

## When to Use

- Building geometry from primitives (`multicuboid`, `multicylinder`, `multisphere`), STL/STEP import, or 2-D `decsg`
- Setting up `femodel` with boundary conditions, loads, materials, and initial conditions
- Solving thermal, structural, or electromagnetic problems (steady, transient, modal, frequency, conduction)
- Post-processing FE results: interpolation, derived quantities, visualization

## When Not to Use

- General-equation PDE (`createpde(N)`) — that legacy workflow is not covered here
- System-level simulation (Simulink/Simscape) — use product-specific skills
- Mesh-only tasks with no PDE solve (e.g., surface meshing for visualization)

## Workflow Overview

1. **Geometry** — Create with primitives, `decsg`, file import, or boolean ops → wrap in `fegeometry`
2. **Model** — `femodel(AnalysisType=..., Geometry=gm)` → material, BCs, loads, ICs
3. **Mesh** — `generateMesh(model)` (default first, refine if needed)
4. **Solve** — `result = solve(model)` or `solve(model, tlist)`
5. **Post-process** — Extract fields, interpolate, compute derived quantities, visualize

## Phase 1: Geometry

### fegeometry — The Hub

```matlab
gm = fegeometry(multicuboid(1, 1, 1));       % From primitives
gm = fegeometry("model.stl");                % From STL/STEP file
gm = fegeometry(decsg(gd, sf, ns));          % From 2-D CSG
gm = fegeometry(nodes, elements);            % From mesh data
```

**`fegeometry` is for the `femodel` workflow only.** Do NOT use `fegeometry` with `createpde(N)` — that legacy workflow uses `geometryFromEdges` (2-D) or `importGeometry` (3-D) instead. This skill covers `femodel` exclusively.

Key properties: `NumCells`, `NumFaces`, `NumEdges`, `Vertices`

### 3-D Primitives

| Function | Origin | Arguments |
|----------|--------|-----------|
| `multicuboid(W, D, H)` | x-y centered, **base at z=0** | Width, Depth, Height |
| `multicylinder(R, H)` | x-y centered, **base at z=0** | Radius, Height |
| `multisphere(R)` | **Centered at origin** | Radius |

Nested cells (vectors), stacked layers (`ZOffset`), hollow (`Void=[true,false]`):

```matlab
gm = fegeometry(multicylinder([0.3, 0.5], 1, Void=[true, false]));  % hollow pipe
gm = fegeometry(multicuboid([1, 1], [1, 1], [0.3, 0.7], ZOffset=[0, 0.3]));  % stacked
```

See `references/primitives-and-import.md` for full options and file import details.

### Boolean Operations

```matlab
gmCombined = union(gm1, gm2);                         % Merge into 1 cell
gmCombined = union(gm1, gm2, KeepBoundaries=true);    % Preserve cells (multi-material)
gmCombined = union(gm1, gm2, KeepBoundaries=[true, false]);  % Selective per shape
gmResult = subtract(gm1, gm2);                        % Cut gm2 from gm1
gmResult = intersect(gm1, gm2);                       % Keep only overlapping region
```

**`KeepBoundaries`**: Use `true` when shapes get different materials (preserves internal faces as cell boundaries). Omit or use `false` to merge into a single cell.

**Cell modification** after boolean ops:

```matlab
gm = mergeCells(gm);              % Merge ALL cells into one
gm = mergeCells(gm, [2, 3]);      % Merge specific cells (must be connected)
gm = deleteCell(gm, cellIDs);     % Remove unwanted cells
```

**Rules:** Union first, subtract last. The function is `subtract` — NOT `subtractgeom`. Never assemble pre-hollowed pieces. Call `mergeCells` only ONCE at the end.

See `references/boolean-and-cell-ops.md` for full strategy (Sculpt+Carve, Void flags, addCell, addVoid, face imprinting).

### 2-D Geometry with decsg

Each shape is a column vector in the geometry matrix. First entry identifies the type:

| Type code | Shape | Column format |
|-----------|-------|---------------|
| `1` | Circle | `[1; xc; yc; r; 0; ...]` |
| `2` | Polygon | `[2; N; x1;...;xN; y1;...;yN]` |
| `3` | Rectangle | `[3; 4; x1;x2;x3;x4; y1;y2;y3;y4]` (CCW corners) |
| `4` | Ellipse | `[4; xc; yc; a; b; angle; 0; ...]` |

All columns must have the same row count — pad shorter ones with zeros. Set formula: `+` (union), `-` (subtract), `*` (intersect).

```matlab
R1 = [3; 4; 0; 1; 1; 0; 0; 0; 0.5; 0.5];
C1 = [1; 0.5; 0.25; 0.15; 0; 0; 0; 0; 0; 0];
gd = [R1, C1]; sf = '(R1-C1)'; ns = char('R1', 'C1')';
gm = fegeometry(decsg(gd, sf, ns));
```

See `references/decsg-and-2d-geometry.md` for polygon vertices, polar-coordinate shapes, extrude, namespace rules.

### Entity Identification

```matlab
topFace = nearestFace(gm, [0, 0, 1]);       % Single point: row vector
faceIDs = nearestFace(gm, [0 0 1; 0 0 0]);  % Multiple points: N×3 matrix
frontEdge = nearestEdge(gm, [0.5, 0, 0.5]);
cellID = findCell(model.Geometry, [x, y, z]); % fegeometry only (not DiscreteGeometry)
facesOfCell = cellFaces(gm, 1);              % All faces of cell 1
facesOfCell = cellFaces(gm, 1, "external");  % Only outer boundary faces
edgesOfCell = cellEdges(gm, 1);
edgeIDs = faceEdges(gm, faceID);
fIDs = facesAttachedToEdges(gm, edgeID);              % Faces sharing an edge
fIDs = facesAttachedToEdges(gm, edgeID, "internal");  % Only internal faces (3-D)
```

**Identify faces/edges BEFORE meshing.** `nearestVertex` does not exist — use `gm.Vertices` + distance calculation.

### Transforms

```matlab
gm = translate(gm, [dx, dy, dz]);
gm = rotate(gm, angle);                          % angle° about z through origin
gm = rotate(gm, angle, [cx cy cz]);              % about z through point [cx,cy,cz]
gm = rotate(gm, angle, [x1 y1 z1], [x2 y2 z2]); % about LINE from pt1 to pt2
gm = scale(gm, [1, 1, -1]);                      % reflect across z=0 (use -1 on axis to flip)
```

**`rotate` 4-arg:** Both args are **points defining the axis line**, not direction+origin. E.g., about y through origin: `rotate(gm, 90, [0 0 0], [0 1 0])`. The 3-arg form ONLY rotates about z.

### Extrude

```matlab
gm3d = extrude(gm2d, [0.1, 0.3, 0.1]);   % 2-D →