vibeflow-openfoam

name

vibeflow-openfoam

description

Use when selecting, generating, running, or debugging VibeFlow OpenFOAM cases from 0-caseDict/caseDict, and when developing, repairing, documenting, compiling, or integrating OpenFOAM UDF code under UDF/, including custom solvers, libraries, boundary conditions, functionObjects, fvOptions, source terms, turbulence/model extensions, Make/files, Make/options, wmake validation, and UDF/README.md development documentation.

VibeFlow OpenFOAM

This skill covers two kinds of work:

• Usage mode: turn 0-caseDict/caseDict and artifacts under B-mesh/ into a runnable, reproducible, cleanable OpenFOAM case under C-run/.
• Development mode: develop, repair, compile, and integrate custom OpenFOAM capabilities under UDF/, then call them from C-run/ cases.

Development mode does not replace usage mode. Development mode proves that a code capability is correct, stable, compilable, and callable; usage mode proves that the current case is closed from a unified physical description to runtime results.

When to Use

• A solver-neutral caseDict must be mapped to an OpenFOAM solver, tutorial family, and dictionary structure.
• C-run needs to be derived from tutorials.
• Meshes need to be converted into OpenFOAM.
• Unified caseDict fields need to be mapped to system/, constant/, and 0 / 0.orig.
• Allrun, Allclean, and optional Allrun.pre need to be completed.
• An OpenFOAM case needs to be run, debugged, or diagnosed.
• A new or modified OpenFOAM solver is needed.
• A custom library, boundary condition, functionObject, fvOption, source term, turbulence model, numerical model, or post-processing utility needs to be added or repaired.
• A model must be implemented from papers, Ref/ material, or OpenFOAM source code.
• Development and integration issues involve UDF/README.md, UDF/src, UDF/solver, Make/files, Make/options, wmake, wclean, libs, or application.

First Decide: Usage Mode or Development Mode

First decide whether the current task modifies case configuration or OpenFOAM code capability.

• Solver selection, tutorial derivation, dictionary generation, mesh conversion, case execution, and case-error debugging: use usage mode.
• C++ work, solver main-loop changes, model classes, boundary conditions, functionObjects, fvOptions, libraries, or solver compilation: use development mode.
• If the development result must be used by the current case, first complete the UDF/ capability and minimal validation in development mode, then return to usage mode and integrate it into C-run/.
• If the issue is only OpenFOAM environment, PATH, bashrc, system libraries, ParaView/pvpython, Gmsh, CadQuery, or other toolchain setup: hand off to vibeflow-toolchain.

What to Read First

For usage mode, read:

• 0-caseDict/caseDict
• references/tutorial-selection.md
  • Use it to select the closest tutorial family, directory topology, and script organization.
• references/dictionary-mapping.md
• references/openfoam-practical-tips.md: OpenFOAM knowledge base, key concepts, failure interpretation, and adapter design notes.
  • Use it to map caseDict into concrete OpenFOAM files and scripts.
• Mesh artifacts and boundary names under B-mesh/.

For development mode, read:

• User requirements and Ref/ material.
• Current UDF/README.md.
• Existing source under UDF/src/ and UDF/solver/.
• The closest native OpenFOAM source:
  • $WM_PROJECT_DIR/applications/solvers/...
  • $WM_PROJECT_DIR/applications/utilities/...
  • $WM_PROJECT_DIR/src/...
  • $WM_PROJECT_DIR/tutorials/...
• If integrating into the current case, also read 0-caseDict/caseDict, system/controlDict, and relevant physical dictionaries under C-run/case-*.

Input

• 0-caseDict/caseDict
• Mesh artifacts under B-mesh/
• UDF/README.md
• UDF/src/
• UDF/solver/
• Ref/
• Local $WM_PROJECT_DIR source code and tutorials

Output

• A runnable case under C-run/
• Standardized directory structure and OpenFOAM dictionaries
• Allrun
• Allclean
• Optional Allrun.pre
• Runtime logs and monitoring results
• Updated UDF/README.md development documentation
• Library source and Make files under UDF/src/<libraryName>/
• Solver source and Make files under UDF/solver/<solverName>/
• Updates to controlDict.application, libs, and relevant model dictionaries under C-run/case-* when needed
• Compilation, linking, loading, and smoke-test records

VibeFlow Standard Case Structure

The generated VibeFlow C-run/ must be a complete OpenFOAM case, not a half-finished collection of only a few dictionary files. Use the following skeleton by default:

C-run/
|-- case.foam
|-- Allrun
|-- Allclean
|-- Allrun.pre                 # Optional; keep only when an independent preprocessing chain exists
|-- 0.orig/                    # Recommended by default; source of truth for initial fields
|   |-- U
|   |-- p / p_rgh
|   |-- T / h / e
|   |-- k / epsilon / omega / nut / nuTilda
|   |-- alpha.* / pointDisplacement / Yi
|   `-- ...
|-- constant/
|   |-- transportProperties / thermophysicalProperties
|   |-- turbulenceProperties
|   |-- phaseProperties
|   |-- g
|   |-- dynamicMeshDict
|   |-- regionProperties
|   |-- triSurface/            # If using snappyHexMesh
|   `-- polyMesh/              # Generated after runtime generation or import
|-- system/
|   |-- controlDict
|   |-- fvSchemes
|   |-- fvSolution
|   |-- decomposeParDict
|   |-- blockMeshDict / snappyHexMeshDict / topoSetDict / setFieldsDict
|   `-- Other auxiliary dictionaries
`-- postProcessing/            # Generated after the run

Structural Constraints

• Treat Allrun and Allclean as required items for a VibeFlow standard case. Add them even if the original tutorial does not have them.
• Prefer keeping 0.orig/ by default, and generate 0/ before the run through restore0Dir or an equivalent workflow.
• 0/ is a runtime artifact and should not be the only long-term manually maintained source of truth.
• Treat constant/polyMesh/, processor*/, time directories, and postProcessing/ as reproducible runtime artifacts, not as canonical inputs.

Multi-Region and Advanced Topologies

• For multi-region cases such as chtMultiRegionFoam, the common structure is:
  • 0.orig/<region>/...
  • constant/<region>/...
  • system/<region>/...
  • Keep constant/regionProperties at the root.
• Some multi-region tutorials use a mixed layout with root-level 0.orig/<field> and region-specific constant/<region>, system/<region>; do not forcibly convert it into another style, and follow the selected tutorial first.
• For overset, nested subcases, and assembled mesh workflows, it is acceptable for the root directory to handle scheduling while subdirectories own their own Allrun.pre, system/, and constant/. For example, overPimpleDyMFoam/cylinder uses a root scheduler plus subcase execution structure.
• Reuse a shared common/ directory only when the tutorial itself follows a multi-world / shared-database pattern. Do not introduce it casually for ordinary single-region or conventional multi-region cases.

Script Conventions

Allrun

• Must exist.
• Should start from the current directory and preferentially reuse OpenFOAM's ${WM_PROJECT_DIR}/bin/tools/RunFunctions.
• Should use helpers such as runApplication, runParallel, getApplication, and restore0Dir instead of extensive handwritten redirection and parallel commands.
• Typical responsibilities:
  • Call ./Allrun.pre.
  • Generate or import the mesh.
  • Run checkMesh.
  • Run setFields / topoSet / changeDictionary.
  • Run decomposePar.
  • Call the solver.
  • Run reconstructPar.
• Should be re-entrant. If existing logs are used to avoid duplicate execution, either follow RunFunctions conventions or document the overwrite strategy clearly.

Allrun.pre

• Create it only when the preprocessing chain can stand as an independent stage.
• Typical responsibilities:
  • blockMesh
  • surfaceFeatureExtract
  • snappyHexMesh
  • splitMeshRegions
  • Mesh assembly, subcase preprocessing, and initial field restoration
• If the root case only schedules multiple subcases, root Allrun.pre may only recurse into subdirectories and execute their preprocessing.

Allclean

• Must exist.
• Should preferentially reuse ${WM_PROJECT_DIR}/bin/tools/CleanFunctions.
• By default it should at least clean:
  • Time directories
  • processor*
  • postProcessing/
  • VTK/, ParaView*, and log files
  • Runtime-generated constant/polyMesh
• It should not delete:
  • 0.orig/
  • Manually maintained system/*.Dict
  • constant/triSurface/
  • Geometry, region, or mesh definition files that the baseline tutorial must keep long term

Core Workflow

Usage-Mode Workflow

1. Read physicalProblem, materials, regions, interfaces, boundariesLoadsInitials, mesh, numericalMethod, and execution.
2. Select the closest baseline case from $WM_PROJECT_DIR/tutorials.
3. Match directory topology first, then solver name.
4. Copy and trim into C-run/, completing the VibeFlow standard skeleton.
5. Import or generate the mesh, then run checkMesh.
6. Write system/, constant/, and 0.orig/ from the unified physical/numerical description in caseDict.
7. Write or fix Allrun, Allclean, and Allrun.pre when needed.
8. Run the solver and monitor residuals, monitored quantities, errors, and divergence.

Development-Mode Workflow

1. Identify the task type:
   • New solver
   • New library
   • New boundary condition
   • New functionObject
   • New fvOption
   • New source term, turbulence model, property model, or numerical model
   • Existing UDF repair
   • Dictionary-only configuration or case integration
2. Define the development boundary:
   • Target capability
   • Inputs and outputs
   • Applicable physical model
   • Target OpenFOAM version
   • Calling method from the current case
   • Minimal validation case
   • Acceptance criteria and non-goals
3. Update UDF/README.md first:
   • Requirements and scope
   • Reference source or papers
   • Mathematical model and discretization meaning
   • Key classes, key files, and dictionary interface
   • File organization plan
   • Build commands
   • Validation method
   • Risks and unverified scope
4. Reuse the smallest skeleton from the closest native OpenFOAM solver, library, utility, or tutorial; avoid writing a main loop or model framework from scratch.
5. Place files by responsibility:
   • Reusable models, boundary conditions, functionObject, fvOption, complex formulas, and utilities go under UDF/src/<libraryName>/.
   • Custom solvers or applications go under UDF/solver/<solverName>/.
6. Write or update Make/files and Make/options.
7. Compile libraries before compiling solvers that call those libraries.
8. Run minimal validation:
   • <solverName> -help
   • libs ("lib<libraryName>.so"); can load
   • A minimal case starts and enters a reasonable iteration loop
   • A user-specified benchmark or smoke test reaches the expected stage
9. If the result is used in the current case, update application, libs, and relevant model dictionaries under C-run/case-*.
10. Write build commands, log locations, error fixes, validation results, and remaining risks back to UDF/README.md.
11. If the capability advances the current workflow, write related state, assumptions, artifacts, and error records back to 0-caseDict/caseDict.

Core Rules

• Do not create OpenFOAM cases from scratch when a close tutorial can be evolved.
• When selecting a tutorial, do not look only at solver name; also check:
  • Single-region / multi-region / multi-world topology
  • 0.orig versus direct 0
  • Whether Allrun.pre exists
  • Whether nested subcases exist
  • Dynamic mesh, overset, or region subdirectories
• If C-run and caseDict drift long term, treat solver-neutral caseDict as the source of truth and bring C-run back into alignment.
• Treat 0.orig/ as the default source of truth for initial fields, and 0/ as the restored runtime copy.
• Prefer explicit dictionary mappings instead of editing isolated entries opportunistically.
• Reuse RunFunctions / CleanFunctions conventions instead of inventing a completely different script interface.
• Put UDF development under UDF/ by default. Do not modify $WM_PROJECT_DIR or HunterFoam core source directly; if upstream source changes are truly required, explain the impact scope and wait for user confirmation.
• For theory-sensitive implementations, read papers, Ref/, and local source first; do not write formulas from experience alone.
• New dictionary keywords need defaults, unit or dimension notes, clear failure errors, and a minimal example.
• When a solver calls a custom library, connect or load it explicitly in both Make/options and case system/controlDict; do not rely on implicit environment state.
• Compilation success is not physical correctness. Theoretical basis, discretization assumptions, and unverified scope must be recorded in UDF/README.md.
• On errors, classify first:
  • Mesh and mesh quality
  • Patch / region naming
  • Physical model selection
  • Numerical discretization and solver settings
  • Initial fields, region splitting, and field-file layout
  • UDF compilation, linking, or dynamic loading
  • UDF dictionary interface and runtime selection tables

Local Source Observations

Based on sampling the local OpenFOAM source tree under $WM_PROJECT_DIR/tutorials:

• Among cases with system/ and constant/, 0.orig/ is clearly more common than maintaining 0/ directly, so VibeFlow should keep 0.orig/ by default.
• Allrun.pre is common in overset, complex mesh generation, and multi-region splitting cases. It should be treated as a standard optional layer, not a special trick.
• Multi-region cases often use constant/<region>/ and system/<region>/ subdirectories; the root also keeps regionProperties, decomposeParDict, and a top-level controlDict.
• A small number of advanced tutorials use the root directory to schedule multiple subcases or use common/ as a shared database; only reuse that structure when the baseline case itself does so.

UDF Directory and Build Conventions

Recommended structure:

UDF/
|-- README.md                  # Development source of truth: requirements, design, build, validation, risks
|-- src/                       # Custom libraries, models, boundary conditions, functionObjects, fvOptions, utilities
|   `-- <libraryName>/
|       |-- Make/
|       |   |-- files
|       |   `-- options
|       `-- ...
|-- solver/                    # Custom solvers or derived applications
|   `-- <solverName>/
|       |-- Make/
|       |   |-- files
|       |   `-- options
|       `-- ...
`-- logs/                      # Optional: build logs, smoke-test logs, error records

Compile a library:

wmake libso UDF/src/<libraryName>

Compile a solver:

wmake UDF/solver/<solverName>

Clean:

wclean libso UDF/src/<libraryName>
wclean UDF/solver/<solverName>

Use the following in UDF/src/<libraryName>/Make/files:

LIB = $(FOAM_USER_LIBBIN)/lib<libraryName>

Use the following in UDF/solver/<solverName>/Make/files:

EXE = $(FOAM_USER_APPBIN)/<solverName>

Make/options principles:

• Explicitly list include paths; do not rely on accidental compile caches.
• Explicitly list linked libraries; do not rely on implicit paths.
• When a solver calls a custom library, add -l<libraryName> to EXE_LIBS.
• If stale dependencies appear after moving or renaming headers, run wclean on the corresponding directory before rebuilding.
• If lnInclude is involved, rebuild links with OpenFOAM tools when necessary; do not manually edit symlinks haphazardly.

If runtime dynamic library loading is needed, add this to system/controlDict:

libs
(
    "lib<libraryName>.so"
);

When integrating a custom solver into a case, set this in system/controlDict:

application     <solverName>;

Development Documentation Requirements

UDF/README.md records at least:

• User requirement and task boundary
• Referenced native OpenFOAM source, tutorial, paper, or Ref/ file
• Mathematical model, governing equations, discretization treatment, and dimension conventions
• Added or changed classes, functions, dictionary keywords, and runtime selection tables
• Code directories, Make files, and dependencies
• Build commands and validation commands
• Integration method with C-run/case-*
• Completed validation, failure records, fix records, and remaining risks

For complex models, do not leave the reasoning only in the final chat response. UDF/README.md must become the development source of truth that later agents and the user can reproduce.

Validation

Usage mode validates at least:

• C-run/ contains at least Allrun, Allclean, constant/, and system/.
• When initial fields are needed, 0.orig/ or the tutorial's equivalent structure exists.
• Mesh conversion or generation succeeds.
• checkMesh has no unresolved fatal errors.
• Dictionaries are consistent with patch / region names.
• system/controlDict application matches the target solver derived from physicalProblem, numericalMethod, and execution.
• Allrun / Allclean invocation paths are valid.
• The solver can start and enter a reasonable iteration loop.
• Residuals or monitored quantities satisfy the current-stage requirements.

Development mode validates at least:

• UDF/README.md is updated and explains why this implementation is used.
• The UDF/src or UDF/solver code structure is clear, and Make/files plus Make/options are complete.
• wmake libso or wmake succeeds; if it fails, the cause and next fix point are recorded accurately.
• The custom library can be loaded by libs (...), or the custom solver can at least run <solverName> -help.
• When integrated into the current case, controlDict.application, libs, and relevant model dictionaries are consistent.
• A minimal case can start, or the current toolchain, mesh, caseDict, or model reason for not starting is stated clearly.
• For theory-sensitive code, formula sources and unverified scope are recorded.

Fallback Rules

• Physical model or boundary conditions are unclear: return to vibeflow-case-dict.
• Mesh quality or patch naming is wrong: return to vibeflow-mesh.
• Geometry itself is wrong: return to vibeflow-geometry.
• OpenFOAM environment, bashrc, compiler, library paths, Python, ParaView, or commands are missing: return to vibeflow-toolchain.
• UDF development is complete and a full case run is needed: continue with usage mode in this skill.
• Results have been generated and plots, scenes, or report material are needed: hand off to vibeflow-postprocess.
• Conclusions and delivery report are needed: hand off to vibeflow-report.