docs: OpenFOAM dam-break skill example + skill hardening from live runs#68
Merged
yannrichet-asnr merged 2 commits intoJun 15, 2026
Merged
Conversation
Add the second worked skill example, skills/examples/openfoam-dambreak-random-sampling.md: the agent builds *both* an OpenFOAM (directory-case) wrapper and a custom random-sampling fzd algorithm from scratch — the "no official fz-* package" path, the inverse of the Newton-cooling example. Validated end to end against OpenFOAM v2412 (interFoam damBreak): an 8-sample obstacle-height study completes in ~30 s. Fold the lessons from running both examples back into the skill: - SKILL.md: a model never says how to *run* the code (that's the calculator) and its tell-tale failure (`Permission denied ./input.txt`); single-file vs case-directory inputs; an fzi prefix-collision check; a locale-safe output tip; a common-failures symptom table; links to both worked examples. - code-wrapper.md: a "Directory-tree (case-based) codes" section; locale-safe numeric output (`LC_ALL=C`); runner-script invocation gotchas (`bash ./script`, exec bit, self-cd). - reference.md: call out the fzd flag divergence (--input_dir/--input_vars, no --format). - howto.md: list the OpenFOAM example. The OpenFOAM example needs the recursive-staging fix (separate PR) to run. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a second end-to-end “fz skill” worked example (OpenFOAM dam-break random sampling) and hardens the skill documentation based on issues encountered during real runs.
Changes:
- Added a new OpenFOAM dam-break example that builds both a directory-case wrapper and a custom
fzdrandom-sampling algorithm from scratch. - Improved skill docs around model-vs-calculator responsibilities, directory-tree staging, locale-safe numeric parsing, runner invocation gotchas, and common failure symptoms.
- Updated reference/howto/changelog to point to the new example and call out
fzdCLI flag differences.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/howto.md | Adds the new OpenFOAM worked example link in the skill walkthrough list. |
| skills/fz/reference.md | Documents fzd’s CLI flag differences vs other fz commands. |
| skills/fz/code-wrapper.md | Adds locale-safe parsing guidance, runner invocation gotchas, and case-directory wrapper notes. |
| skills/fz/SKILL.md | Clarifies single-file vs case-directory usage, model-vs-calculator responsibilities, adds failure symptom table, and links both examples. |
| skills/examples/openfoam-dambreak-random-sampling.md | New full worked example: OpenFOAM wrapper + custom fzd random sampling algorithm. |
| NEWS.md | Updates changelog with the new example and documentation hardening summary. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+146
to
+153
| { | ||
| "id": "OpenFOAM", | ||
| "varprefix": "%", | ||
| "commentline": "//", | ||
| "output": { | ||
| "peak_height": "LC_ALL=C awk '!/^#/ && NF {v=$2+0; if (v>m) m=v} END {print m}' postProcessing/interfaceHeight1/0/height.dat" | ||
| } | ||
| } |
Comment on lines
+169
to
+172
| #!/bin/bash | ||
| # OpenFOAM.sh — fz runner for the damBreak wrapper. Usage: OpenFOAM.sh <compiled case dir> | ||
| [ -d "$1" ] && cd "$1" | ||
| command -v blockMesh >/dev/null || { echo "OpenFOAM environment not sourced" >&2; exit 2; } |
| occurrence of `0.32876` in `system/blockMeshDict` with the fz variable: | ||
|
|
||
| ```bash | ||
| sed -i 's/0.32876/%obstacle_height/g' case/system/blockMeshDict # 8 vertex rows |
Comment on lines
+72
to
+75
| - Make numeric extraction **locale-independent**: prefix the command with `LC_ALL=C`. | ||
| Under a non-English locale (comma decimal), `sort -g` mis-orders period/scientific-notation | ||
| numbers and can return a wrong "max"; prefer a one-pass `awk` max/min, e.g. | ||
| `LC_ALL=C awk '!/^#/ && NF {if ($2+0>m) m=$2+0} END {print m}' out/series.dat`. |
Soften the fzd flag-divergence note: newer fz also accepts the fzi/fzc/fzr input flag names as aliases (see the fzd alias PR); fz 1.0 on PyPI takes only the canonical --input_dir/--input_vars. The no---format point is unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the second worked fz skill example and folds back the lessons learned from running both examples end to end.
New example — build everything from scratch
skills/examples/openfoam-dambreak-random-sampling.md: the agent authors both an OpenFOAM (directory-case) wrapper and a custom random-samplingfzdalgorithm, because nofz-*package exists — the deliberate inverse of the Newton-cooling example (which reuses ready-made packages).Validated end to end against OpenFOAM v2412 (
interFoamdamBreak): wrapper runs throughfzr/fzd, and an 8-sample obstacle-height study finishes in ~30 s with peak water height spread ~0.08–0.18 m.Skill hardening (from real failures hit while validating)
Permission denied ./input.txt); single-file vs case-directory inputs; anfziprefix-collision check; a locale-safe output tip; a common-failures symptom table; links to both worked examples.LC_ALL=C— a non-English locale silently makessort -greturn a wrong max); runner-script invocation gotchas (bash ./script, exec bit, self-cdcd "${0%/*}").fzdflag divergence (--input_dir/--input_vars, no--format).Depends on #67
The OpenFOAM example is a directory-case code, so it needs the recursive-staging fix in #67 to run. Merge #67 first. (Docs-only here; no functional dependency at commit time.)
🤖 Generated with Claude Code