feat(formdsl): add convection-diffusion DG step simulations

README.md

@@ -159,6 +159,38 @@ uv run python scripts/plot_poisson_galerkin_figure_pack.py --profile quick
 
 See `docs/poisson-galerkin-solver.md` and `docs/poisson-benchmarks.md`.
 
+## FormDSL step simulations
+
+Run dealii-style step examples for end-to-end FormDSL simulations:
+
+```bash
+uv run python scripts/run_formdsl_step_001_iga_poisson.py --resolution 16
+uv run python scripts/run_formdsl_step_002_iga_multipatch_poisson.py --resolution 8
+uv run python scripts/run_formdsl_step_003_dgsem_poisson.py --resolution 24
+```
+
+Step 003 runs a DGSEM convection-diffusion prototype over a CUTKIT clipped
+overlay.
+
+DGSEM lowering inspection remains available via:
+
+```bash
+uv run python scripts/run_formdsl_dgsem_lowering_example.py --flux sipg
+```
+
+DGSEM step execution requires grudge dependencies and uses a CUTKIT clipped
+overlay from the Section 6.1.1 trimmed panel:
+
+```bash
+uv sync --extra dgsem
+uv run python scripts/run_formdsl_step_003_dgsem_poisson.py --resolution 24
+```
+
+Each step script now emits SVG plot artifacts by default under
+`.artifacts/formdsl-step-00x` (disable via `--skip-plots`).
+
+Details: `docs/formdsl-step-simulations.md`.
+
 ## Development workflow notes
 
 - Python requirement: `>=3.12`.

docs/exec-plans/completed/20260407-step003-convection-diffusion.md

@@ -0,0 +1,43 @@
+# Step-003 Convection-Diffusion Upgrade
+
+## Objective
+
+Upgrade FormDSL DG step-003 from diffusion/reaction-only Poisson prototype to a
+convection-diffusion setup, while keeping trimmed-overlay execution and end-to-end
+runtime validation on `ipa`.
+
+## Scope
+
+- Add DGSEM capability/lowering support for a `convection` term kind.
+- Extend DGSEM solver assembly to include a convection contribution.
+- Use a non-symmetric linear solve path when convection is present.
+- Update step-003 payload/labels/docs to describe convection-diffusion.
+- Add/adjust tests for new term support and behavior.
+
+## Acceptance Criteria
+
+- `assemble_form(..., backend="dgsem")` accepts `convection` terms.
+- Step-003 form includes a convection term and no longer presents itself as
+  Poisson-only.
+- Local checks pass (`make dev`).
+- Step-003 run on `ipa` succeeds for at least one resolution with convection and
+  reports passing residual checks.
+
+## Checklist
+
+- [x] Add `convection` to DGSEM supported-term capabilities.
+- [x] Extend DGSEM lowering to emit deterministic convection volume lowering.
+- [x] Extend solver matrix assembly with convection contribution.
+- [x] Add non-symmetric linear solve fallback for convection cases.
+- [x] Update step-003 form payload and reporting strings.
+- [x] Update/expand FormDSL tests for convection support.
+- [x] Validate locally and on `ipa`.
+
+## Outcomes
+
+- DGSEM now supports `convection` in capability checks and lowering payloads.
+- Step-003 payload and reporting now describe convection-diffusion.
+- DGSEM solve path now chooses a non-symmetric solver when convection is present
+  (`bicgstab` with `cgne` fallback).
+- Local `make dev` passes, and `ipa` step-003 runs pass at resolutions 8, 16,
+  and 24.

docs/formdsl-step-simulations.md

@@ -0,0 +1,97 @@
+# FormDSL Step Simulations
+
+This page provides dealii `step-xxx` style end-to-end examples for CUTKIT
+FormDSL workflows.
+
+## Step 001: Single-Patch Poisson (IGA)
+
+Run a full trimmed-domain Poisson solve through:
+
+- FormDSL parsing,
+- IGA assembly,
+- CG linear solve,
+- and reference-error check against a higher-order solve.
+
+```bash
+uv run python scripts/run_formdsl_step_001_iga_poisson.py --resolution 16
+```
+
+Useful options:
+
+- `--backend-mode jplus|folded`
+- `--artifact-dir <path>`
+- `--skip-plots`
+- `--manifest-path <path>`
+- `--max-abs-error <tol>`
+
+By default this script writes an SVG figure pack under
+`.artifacts/formdsl-step-001`.
+
+## Step 002: Multipatch Interface-Coupled Poisson (IGA)
+
+Run a full multipatch-flavored solve with deterministic interface coupling
+metadata in the payload and repeated-assembly determinism checks.
+
+```bash
+uv run python scripts/run_formdsl_step_002_iga_multipatch_poisson.py --resolution 8
+```
+
+Useful options:
+
+- `--artifact-dir <path>`
+- `--skip-plots`
+- `--manifest-path <path>`
+- `--max-residual <tol>`
+- `--max-repeat-coeff-diff <tol>`
+
+By default this script writes an SVG figure pack under
+`.artifacts/formdsl-step-002`.
+
+## Step 003: DGSEM Convection-Diffusion Prototype (End-To-End Solve)
+
+Run a DGSEM-style end-to-end convection-diffusion solve through FormDSL DG
+lowering and a linear solve path with a real CUTKIT trimmed overlay built from
+the Section 6.1.1 B-spline panel clipped against a Cartesian background grid:
+
+```bash
+uv run python scripts/run_formdsl_step_003_dgsem_poisson.py --resolution 24
+```
+
+Useful options:
+
+- `--resolution <n>`
+- `--sample-count <n>`
+- `--overlay-quadrature-order <n>`
+- `--artifact-dir <path>`
+- `--skip-plots`
+- `--manifest-path <path>`
+
+By default this script writes SVG artifacts under `.artifacts/formdsl-step-003`:
+
+- trimmed overlay geometry,
+- clipped-cell classification,
+- and a DG solve profile chart.
+
+`grudge` mode requires the `dgsem` extra plus a working
+OpenCL platform (`uv sync --extra dgsem`).
+
+No CUTKIT runtime compatibility shims are applied. The `dgsem` extra pins a
+tested grudge compatibility window (`grudge==2021.1`, `meshmode==2021.2`,
+`loopy==2024.1`, `modepy==2021.1`, `pymbolic==2024.2.2`,
+`pytools==2024.1.21`).
+
+## DG-SEM Status
+
+The core `dgsem` backend contract remains deterministic lowering payload
+first (operator-chain descriptors and diagnostics).
+
+`solve_form(..., backend="dgsem")` now runs the grudge execution path only
+(optional dependencies + OpenCL).
+
+Production-grade grudge operator execution semantics are still evolving.
+
+For lowering inspection:
+
+```bash
+uv run python scripts/run_formdsl_dgsem_lowering_example.py --flux sipg
+```

docs/index.md

@@ -26,11 +26,15 @@ Repository-local documentation is the system of record for CUTKIT.
 - `docs/poisson-benchmarks.md`: Poisson-oriented benchmark usage and profiles
 - `docs/poisson-galerkin-solver.md`: immersed Poisson Galerkin solve + validation workflow
 - `docs/formdsl-parity-benchmarks.md`: shared IGA + DG-SEM formdsl parity benchmark usage
+- `docs/formdsl-step-simulations.md`: dealii-style FormDSL end-to-end step runs
 - `docs/formdsl-nurbs-multipatch-evaluation.md`: Phase 3 evaluation notes for NURBS mapping and multipatch rollout
 - `docs/ufl-backend-support.md`: UFL form backend support matrix and diagnostics
 - `scripts/check_docs_freshness.py`: stale docs path + markdown-anchor checker
 - `scripts/minimize_cutpanel_fuzz_cases.py`: deterministic fuzz-candidate minimizer
 - `scripts/run_formdsl_parity_benchmark.py`: run formdsl convergence + parity benchmark examples
+- `scripts/run_formdsl_step_001_iga_poisson.py`: step-001 end-to-end FormDSL IGA Poisson solve
+- `scripts/run_formdsl_step_002_iga_multipatch_poisson.py`: step-002 multipatch FormDSL IGA Poisson solve
+- `scripts/run_formdsl_step_003_dgsem_poisson.py`: step-003 FormDSL DGSEM solve prototype
 - `docs/entire-transcript-policy.md`: Entire transcript handling policy
 - `.github/workflows/weekly-janitor.yml`: scheduled repository cleanup automation
 

docs/ufl-backend-support.md

@@ -78,6 +78,7 @@ deterministic conventions:
 | Term kind | iga | dgsem |
 | --- | --- | --- |
 | `diffusion` | yes | yes |
+| `convection` | no (`unsupported_term`) | yes |
 | `mass` | yes | yes |
 | `reaction` | yes | yes |
 | `source` | yes | yes |
@@ -159,6 +160,50 @@ Current family operator behavior in lowering payloads:
 | `central` | `bdry_trace_pair -> project -> face_mass` | `interior_trace_pairs -> project -> face_mass` | ignores `dg_penalty` |
 | `upwind` | `bdry_trace_pair -> project -> face_mass` | `interior_trace_pairs -> project -> face_mass` | ignores `dg_penalty` |
 
+## DG Lowering Example (No Solve Execution)
+
+Use the DGSEM lowering example script when you want to inspect the deterministic
+payload and operator chains CUTKIT emits for a form:
+
+```bash
+uv run python scripts/run_formdsl_dgsem_lowering_example.py --flux sipg
+```
+
+The script always reports `execution_mode = lowering_only`, prints volume/trace/
+flux signatures, and can optionally emit a JSON manifest via
+`--manifest-path`.
+
+## End-To-End Solve Helper
+
+`cutkit.formdsl.solve_form(...)` now provides one end-to-end linear solve helper
+for both backends:
+
+- `backend="iga"`: assembled trimmed-domain IGA matrix + CG solve.
+- `backend="dgsem"`: DG lowering plus grudge-backed execution mode:
+  - `dgsem_execution_mode="grudge"` (requires `dgsem` extra and OpenCL).
+  - symmetric systems use CG; convection-enabled systems use non-symmetric
+    solve (`bicgstab` with deterministic `cgne` fallback).
+  - The `dgsem` extra pins a grudge-compatible package window:
+    `grudge==2021.1`, `meshmode==2021.2`, `loopy==2024.1`,
+    `modepy==2021.1`, `pymbolic==2024.2.2`, `pytools==2024.1.21`.
+
+## FormDSL End-To-End Step Examples
+
+For dealii-style end-to-end runs, use the step scripts:
+
+```bash
+uv run python scripts/run_formdsl_step_001_iga_poisson.py --resolution 16
+uv run python scripts/run_formdsl_step_002_iga_multipatch_poisson.py --resolution 8
+uv run python scripts/run_formdsl_step_003_dgsem_poisson.py --resolution 24
+```
+
+These execute full simulation loops (assembly + linear solve + checks).
+Step 003 builds a real CUTKIT clipped overlay from the Section 6.1.1 trimmed
+panel before running DG lowering and a convection-diffusion solve.
+
+All step scripts also emit SVG plot artifacts by default (override path with
+`--artifact-dir`, disable with `--skip-plots`).
+
 ## Backend Parity Benchmark Example
 
 Use the formdsl parity benchmark runner for a shared IGA + DG-SEM example:

pyproject.toml

@@ -30,8 +30,12 @@ forms = [
   "ufl>=2017.1.0"
 ]
 dgsem = [
-  "grudge>=2021.1",
-  "meshmode>=2021.1"
+  "grudge==2021.1",
+  "meshmode==2021.2",
+  "loopy==2024.1",
+  "modepy==2021.1",
+  "pymbolic==2024.2.2",
+  "pytools==2024.1.21"
 ]
 perf = [
   "numpy>=2"