OpenFOAM 14 Part 8: Reading and Creating Cases Independently

The workflow in the figure is a loop, not a line: the “Explain” step of one change produces the next question. What makes it engineering rather than trial and error is that every step leaves a verifiable trace. The table maps each step onto the OpenFOAM v14 tool that produces that trace and onto the part of this series where the tool was introduced.

Two consequences follow. First, a change that cannot be traced back to a source is not finished, even if the run succeeds. Second, a failure is not wasted time: if each step was recorded, the step at which the chain broke is visible, and the diagnosis starts from there rather than from the beginning.

The seven rows above cover the capstone. In practice the same classification extends to other frequent requests. The rows below fill the most common gaps; each one names the v14 file and the User Guide chapter where the syntax is documented.

The hypothesis line has a precise form: “to obtain X, I change entry Y in file Z, and I expect W.” If you cannot fill in Y and Z, the classification step is not finished; if you cannot fill in W, you will not be able to tell whether the change worked.

The useful distinction above is the root of many errors, so it is worth making it concrete. The mesh layer lives in constant/polyMesh/boundary, generated by blockMesh from the boundary list of blockMeshDict (Part 2). Each patch has a name, a geometric type (patch, wall, empty, symmetryPlane, wedge, cyclic…), a number of faces and a start face. The field layer lives in 0/U, 0/p, and so on (Part 3): for each patch name, a boundary condition tells the solver how that variable behaves there. The initial-field layer is the internalField of the same files: the starting value in the cells, which in a steady run is only an initial guess.

// constant/polyMesh/boundary (generated by blockMesh, excerpt)
frontAndBack
{
    type            empty;
    nFaces          2560;
    startFace       2656;
}

// 0/U (written by you)
frontAndBack { type empty; }

Two rules connect the layers. (1) Every patch name in the mesh must appear in the boundaryField of every field that the solver reads (a regular-expression key such as "(walls|frontAndBack)" also counts). (2) Constraint types (empty, wedge, symmetryPlane, cyclic, processor) are geometric statements, and the field must repeat the same constraint type on that patch: an empty mesh patch with a fixedValue velocity is rejected when the field is read. Generic patch and wall patches, instead, accept any compatible physical condition – that is where the modelling choice happens. With many patches it is easy to miss one; check it mechanically:

# Patch names known to the mesh (checkMesh prints them with face counts)
checkMesh | sed -n '/Patch/,/^$/p'
# Patch names known to each field file
foamDictionary -entry boundaryField -keywords 0/U
foamDictionary -entry boundaryField -keywords 0/p

The official v14 guide has 8 chapters and 39 numbered sections. The table lists the pages that correspond to the topics of this series, with their exact titles (Chapter 6 is officially called “Field and boundary initialisation”: besides boundary conditions it covers field functions and field sources).

Two pitfalls when searching the web. Pages from the other OpenFOAM family (openfoam.com, version numbers such as v2312 or v2406) describe a different code base with different solver names and file names. Pages for older Foundation versions (for example v8 or v10) describe the same family before the modular solvers. In both cases the URL or the version selector tells you immediately: for this course it must say user-guide-v14.

The source header of the v14 condition (src/finiteVolume/fields/fvPatchFields/derived/flowRateInletVelocity/) describes it as a velocity inlet whose velocity is normal to the patch and adjusted to match a specified mass flow rate, volumetric flow rate or mean velocity, with an optional profile. Exactly one of the three flow specifications must be given. Its documented properties are:

This is exactly why changing type fixedValue; to type flowRateInletVelocity; alone fails: the new condition does not read a prescribed vector, it needs a flow quantity. For the capstone channel the equivalent of U = 0.01 m/s through an inlet of 0.020 m × 0.001 m is Q = 0.01 × 0.020 × 0.001 = 2 × 10⁻⁷ m³/s:

inlet
{
    type                flowRateInletVelocity;
    volumetricFlowRate  2e-07;       // m^3/s = 0.01 m/s * 0.020 m * 0.001 m
    // alternatives (one of the three):
    // meanVelocity     0.01;        // m/s
    // massFlowRate     ...;         // kg/s, needs rho or rhoInlet
    // profile          laminarBL;   // optional velocity profile
    value               uniform (0 0 0);
}

The evidence record for this choice would read: (1) prescribe the flow rate rather than a velocity vector; (2) User Guide 4.7.5 (foamInfo) and the source header; (3) the example cases that foamInfo flowRateInletVelocity lists; (4) the listing above; (5) it applies because the inlet is a plane patch with a well-defined normal and the quantity of interest is the flow rate. The heading of the example above calls it “turbulent”; in fact the condition is not specific to turbulence – it is used in laminar and turbulent cases alike, and the turbulentBL profile is only one option.

Two cases with identical directory trees can solve different problems. The signatures are in three files, which is why the warning says to read them together:

Copying the fvSolution of a transient tutorial into a steady case (or the reverse) usually does not fail at parse time; it fails later, as divergence or as an absurdly slow run. The v14 tutorial incompressibleFluid/pitzDailySteady is the reference steady example: steadyState in fvSchemes, a SIMPLE dictionary with consistent yes; and residualControl in fvSolution.

Run on the capstone fvSchemes of section 26, the queries give a predictable output. The first (no -entry) prints the whole file as the parser understood it, without comments and with normalised layout: a quick way to see whether a misplaced brace has swallowed half of the file. The second prints only the divSchemes sub-dictionary. The last two give:

$ foamDictionary -entry divSchemes -keywords system/fvSchemes
default
div(phi,U)
div((nuEff*dev2(T(grad(U)))))

$ foamDictionary -entry "divSchemes/div(phi,U)" -value system/fvSchemes
bounded Gauss upwind

Why the quotes: without them, Bash interprets the parentheses of div(phi,U) as shell syntax and stops with a syntax error before foamDictionary even starts. Other options documented in User Guide 4.7.2, all useful for evidence gathering:

foamDictionary -help                                   # authoritative option list
foamDictionary -expand system/fvSchemes                # macros and #include expanded
foamDictionary -entry divSchemes -keywords system/fvSchemes
foamDictionary -entry "divSchemes/turbulence" -add "bounded Gauss upwind" system/fvSchemes
foamDictionary -set "startFrom=startTime, startTime=0" system/controlDict
foamDictionary -entry boundaryField -keywords 0/U      # patch names in a field file

-expand prints the file after #include and $macro substitution, that is, what the solver will actually receive. -add creates an entry that does not exist yet; -set changes an existing one and accepts a comma-separated list of keyword=value assignments. The last line of the listing applies the same structural reading to a field file: the keywords of boundaryField are the patch names that the field declares – the first thing to compare with the mesh when an error says that a patch entry cannot be found. When in doubt about an option, foamDictionary -help on your installation is authoritative.

Applied to a copy of the v14 tutorial pitzDailySteady (whose original entry is bounded Gauss linearUpwind grad(U)), the essential part of the diff -u output looks like this: lines starting with - are in the saved copy only, lines starting with + in the edited file only, the others are unchanged context.

--- system/fvSchemes.before-ex08
+++ system/fvSchemes
@@ (line numbers) @@
 divSchemes
 {
     default         none;
-    div(phi,U)      bounded Gauss linearUpwind grad(U);
+    div(phi,U)      bounded Gauss upwind;
     div(phi,k)      bounded Gauss limitedLinear 1;
     div(phi,epsilon) bounded Gauss limitedLinear 1;

Because foamDictionary -set rewrites the file through the parser, the diff may also show layout changes (alignment, removed comments) elsewhere. That is one more reason to keep the .before-ex08 copy: reverting is a single command, and the experiment is reversible by construction.

cp system/fvSchemes.before-ex08 system/fvSchemes     # restore the original

Why the change is “an exercise, not a universal best scheme”. Gauss upwind takes the face value from the upstream cell: it is bounded and robust but only first-order accurate, and its truncation error behaves like an artificial diffusion ν_num ≈ |u|Δx/2. For the capstone mesh, Δx = 0.30/80 = 3.75 mm and U = 0.01 m/s, so ν_num ≈ 1.9 × 10⁻⁵ m²/s – about twice the physical viscosity of 1.0 × 10⁻⁵ m²/s in the streamwise direction. In the developed part of a channel the streamwise gradients vanish and the damage is small; in the entrance region, or in any flow not aligned with the mesh, it is not. The cell Péclet number U Δx/ν = 3.75 is above 2, the value beyond which pure central differencing (Gauss linear) can produce wiggles: this is the trade-off that Part 5 discusses in detail. The bounded prefix, used in steady-state runs, subtracts the term (∇·φ)U so that the discretised convection remains well behaved while continuity is not yet satisfied during the iterations.

foamSearch (User Guide 4.7.3) takes three arguments: a directory, a file name and an entry path. It finds every file with that name below the directory, extracts the entry with foamDictionary and prints the distinct values found. With -c it also counts how many files contain each value (in the guide’s example GAMG is the most common p solver, followed by PCG, smoothSolver and PBiCGStab). The output therefore tells you which spellings exist and how often, but not where. To go from a value to a case, combine it with ordinary tools, then interrogate each candidate case structurally:

# Which tutorials use each p solver, and with which time scheme?
foamSearch "$FOAM_TUTORIALS" fvSolution solvers/p/solver
grep -rl "GAMG" --include=fvSolution "$FOAM_TUTORIALS" | head -n 5
# For one candidate case directory <case>:
foamDictionary -entry ddtSchemes/default -value <case>/system/fvSchemes
foamDictionary -entry simulationType -value <case>/constant/momentumTransport
foamDictionary -entry solver -value <case>/system/controlDict

For the exercise, choose two tutorials whose p solvers differ (for instance GAMG and PCG/PBiCGStab) and fill a small table: tutorial path; ddtSchemes/default (steady or transient); simulationType (laminar, RAS, LES); solver module; mesh size (from checkMesh or the blockMeshDict). The differences that prevent a simple comparison are typically: a transient pressure equation is solved many times per time step with a good initial guess, whereas a steady one is solved once per iteration with a loose relTol; a turbulent case adds fields and changes the conditioning of the momentum equation; a larger mesh favours multigrid. A solver choice is a response to all of these at once, so its frequency says nothing about its suitability for your case.

foamInfo (User Guide 4.7.5) searches the OpenFOAM source for the class that implements the name you give, prints the Description and Usage sections of its header – the same text the developers maintain next to the code – and lists tutorial cases in which the name appears. The four queries above cover four different families: incompressibleFluid is a solver module, flowRateInletVelocity a boundary condition, kOmegaSST a RAS momentum-transport model, linearRamp a Function1 (a function of time or of another scalar, used inside many conditions). The guide documents further examples such as foamInfo kEpsilon, foamInfo Function1 and foamInfo triSurfaceMesh.

Reading the Usage table: the column “Required” separates the keywords that must be present from those with a default. For a boundary condition, the class name itself tells the field type: …FvPatchVectorField conditions apply to vector fields such as U, …FvPatchScalarField to scalar fields such as p or T, and templated …FvPatchField conditions (such as fixedValue, zeroGradient, uniformFixedValue) exist for every field type. A filled worksheet for the example row:

Almost every type, solver, model or viscosityModel keyword in OpenFOAM selects a C++ class at run time by name. Each family registers its members in a run-time selection table when its library is loaded. foamToC (“table of contents”, User Guide 4.7.6) loads the libraries and prints those tables: -scalarBCs and -vectorBCs list boundary conditions by field type, -solvers the solver modules (equivalent to -table solver), -functionObjects, -fvModels and -fvConstraints the corresponding families, -tables the names of all tables (the default with no options), -table <name> one table, and -search <name> the table(s) in which a name appears. -solver <module>, -libs and -noLibs control which libraries are loaded, so that the listing matches what a given solver actually sees.

foamToC -vectorBCs | grep -i flowRate      # is it a vector-field condition?
foamToC -scalarBCs | grep -i flowRate      # (should not appear for scalars)
foamToC -tables | less                      # every run-time selection table
foamToC -solver incompressibleFluid -functionObjects

The second command is the mechanical version of the warning in section 07: if a condition appears under -vectorBCs but not under -scalarBCs, it cannot be used for p. The same table is what the solver prints when a name is misspelt or belongs to a library that is not loaded – the error message pattern is recognisable:

--> FOAM FATAL IO ERROR:
Unknown patchField type flowRateInletVelocty for patch inlet of field U

Valid patchField types are :
...  (the list of every vector condition that is loaded)

Reading it: the first line gives the wrong name, the patch and the field; the list that follows is the selection table. Search it for the intended name; if it is absent, the library that provides it is not loaded or the object does not exist in v14. foamToC -search BirdCarreau answers the question “which table is this name in?” (here the table of generalised-Newtonian viscosity models, which is why the next command in the listing names generalisedNewtonianViscosityModel).

foamFind (User Guide 4.7.8) locates a file in the OpenFOAM source tree (by default in $FOAM_SRC) and can print it (-print), search it for a word (-search, case-insensitive -isearch), show line numbers (-numbers), open it in an editor (-edit) or return the build files associated with it (-files for Make/files, -options for Make/options). The search root can be changed with -applications, -modules, -tutorial or -dir: foamFind -modules incompressibleFluid.C looks only in the solver-module sources. Typical uses in this course: confirm the exact keyword a class reads (search the .C file for lookup or for the keyword itself), and read the Description/Usage block of a header when foamInfo output is not enough. None of these commands touches your case.

Details from User Guide 4.7.1, 4.7.4, 4.7.7 and 4.7.9 that matter in practice:

• foamListTimes lists the time directories excluding 0 by default; with -rm it deletes the listed directories. On the capstone it should print 50, 100, 150, 200, 250, 300.
• foamCleanCase returns a case to its original state: it removes time directories other than 0, post-processing output (postProcessing, VTK), processor* directories, dynamic code and constant/polyMesh. After it, blockMesh must be run again. In a case whose mesh came from an external converter, that mesh is gone.
• foamCloneCase oldCase newCase creates a new case from the 0, system and constant directories of the old one (with -processor it also copies processor directories): the right way to make the “disposable copy” this unit keeps asking for.
• foamGet patchFlowRate copies a packaged configuration file into system/; foamGet functions copies a template functions file. The v14 User Guide (7.2) recommends listing function objects in a functions file in the case system directory, with #includeFunc; foamPostProcess -list lists the packaged ones.
• foamUnits without arguments lists every named dimension and unit; foamUnits power shows the dimension set of power (kg m² s⁻³, i.e. watts); foamUnits mm shows the factor 0.001 to metres that units [mm]; uses in Part 2. It also converts: foamUnits cal "lbf*m".
• checkMesh is read-only for the mesh, but when it finds failing cells or faces it writes them as sets in constant/polyMesh/sets/ for inspection; -allGeometry and -allTopology enable extra checks.
• Also in 4.7: foamMergeCase and foamUnMergeCase overlay the files of a variant on a base case and undo the overlay – useful once you maintain several variants of the same case.

foamListTimes                 # 50 100 150 200 250 300 (0 is excluded by default)
foamListTimes -rm             # DESTRUCTIVE: deletes the listed time directories
foamCloneCase step08_channel step08_channel_ex2   # copies 0, system, constant
foamGet patchFlowRate         # copies a function-object file into system/
checkMesh -allGeometry -allTopology

Expected results of the five commands on a correct installation: foamVersion reports OpenFOAM-14; $WM_PROJECT_DIR points to an OpenFOAM-14 directory; $FOAM_TUTORIALS to its tutorials subdirectory; command -v foamRun prints the path of the executable (an empty answer means the environment is not sourced); foamInfo incompressibleFluid prints the description of the module. If any of these fails, stop: nothing that follows will be reliable.

In the modular architecture a single executable, foamRun, reads solver from controlDict and loads the corresponding module library (the -solver option of foamRun can override it). Material written for older Foundation releases or for the openfoam.com family uses different names. The most frequent translations:

// Older / other-family input that will NOT work as-is in Foundation v14
application     simpleFoam;          // v14: solver incompressibleFluid; + foamRun
// constant/transportProperties       // v14: constant/physicalProperties
// constant/turbulenceProperties      // v14: constant/momentumTransport
// postProcess -func ...              // v14: foamPostProcess -func ...

In the Foundation line, momentumTransport replaced turbulenceProperties around v8, physicalProperties replaced transportProperties around v10, and solver modules with foamRun and foamPostProcess arrived with v11. v14 also accepts named dimensions such as [velocity] and [kinematicPressure] in field files, equivalent to the numeric vectors used in this unit. If an internet example uses any of the old names, treat it as a hint about concepts, never as text to paste.

The find command at the end should print exactly four lines – the case directory and its three empty subdirectories:

.
./0
./constant
./system

At the end of the capstone the case contains nine editable files plus the generated mesh. The inventory below is also a checklist: one line per file, with the class or the key entry that identifies it.

step08_channel/
├── 0/
│   ├── U                     volVectorField, [0 1 -1 0 0 0 0]
│   └── p                     volScalarField, [0 2 -2 0 0 0 0]
├── constant/
│   ├── physicalProperties    viscosityModel constant; nu
│   ├── momentumTransport     simulationType laminar;
│   └── polyMesh/             generated by blockMesh, never edited by hand
└── system/
    ├── blockMeshDict
    ├── controlDict           solver incompressibleFluid;
    ├── fvSchemes
    └── fvSolution

Why the order matters. blockMesh needs system/controlDict to exist (every OpenFOAM application reads it at start-up), so in practice the first two files written are blockMeshDict and a minimal controlDict; the solver entry can be completed later. Fields depend on patch names, which come from the mesh. Schemes depend on the terms of the equations, which depend on the physics (a laminar model has no div(phi,k)). Writing in this order means that each file can be checked against something that already exists. Every file needs a FoamFile header with at least format, class and object (Part 1); version and location are optional.

> log.x 2>&1 sends both standard output and standard error to the log, so that the error message – written on standard error – is not lost. An OpenFOAM fatal input error has a fixed structure (the layout below is schematic):

--> FOAM FATAL IO ERROR:
<what was expected and what was found>

file: <case>/system/fvSchemes/divSchemes at line <n>.

    From function ...
    in file ... at line ...

FOAM exiting

The message line answers question 3 (what was expected); the file: line answers question 2, and its path continues inside the file down to the sub-dictionary (.../fvSchemes/divSchemes), with the line number; the From function line names the C++ function, which often reveals the family involved (a boundary-condition constructor, a scheme selector, a model). Question 1 comes from which log the error is in. The other three questions are checks you make yourself: checkMesh or the boundary file for 4, the FoamFile class and the dimensions line for 5, the relevant dictionary for 6.

Plain FOAM FATAL ERROR (without “IO”) usually concerns a state rather than a file – for instance a missing field or an inconsistent dimension in an operation. Warnings (--> FOAM Warning) do not stop the run but often explain a later failure. Useful commands:

set -o pipefail
foamRun 2>&1 | tee log.foamRun          # watch and keep the log
grep -n "FOAM FATAL" log.*              # first fatal message, with line number
grep -n -i "warning" log.foamRun | head # warnings printed before the failure

set -o pipefail makes the exit status of a pipeline that of the failing program rather than that of tee, so that a script stops at the right stage. The “first meaningful error” is the first fatal message, not the last lines of a long cascade of consequences.

The missing delimiter is the semicolon after value uniform (0.01 0 0). In the OpenFOAM dictionary language (Part 1) a primitive entry is a keyword followed by tokens up to a ;. Without it the parser keeps reading the tokens of value and reaches the closing brace of inlet while the entry is still open; the error is reported as a malformed (ill-defined) entry starting at keyword value, with the line range the parser tried to read. The line number in the message is therefore often the line after the real fault: look backwards from it. The fix is one character:

inlet
{
    type       fixedValue;
    value      uniform (0.01 0 0);
}

Other syntax faults and their signatures: an unbalanced brace usually produces an end-of-file error or swallows the rest of the file (visible immediately with foamDictionary <file>, which prints the structure as understood); a vector written without parentheses, or with commas, produces a wrong-token error when the field is read; uniform 0.01 in a vector field fails because a scalar is not a vector. In all these cases foamDictionary on the single file reproduces the error in a fraction of a second, without running the solver.

For constant density ρ, the incompressible momentum equation is divided by ρ: ∂U/∂t + ∇·(UU) = −∇(p/ρ) + ∇·(ν∇U) + … The variable solved by incompressibleFluid is therefore p_k = p/ρ, with units m²/s². The dimension vector lists the exponents of the seven base dimensions in the fixed order [mass length time temperature moles current luminous-intensity] (kg, m, s, K, mol, A, cd): [0 2 -2 0 0 0 0] is m² s⁻², [0 1 -1 0 0 0 0] is m s⁻¹, whereas a pressure in pascals would be [1 -1 -2 0 0 0 0]. In v14 the same can be written with named dimensions, [kinematicPressure] and [velocity] (the official pitzDailySteady uses dimensions [kinematicPressure];).

If 0/p declares pascals, OpenFOAM checks dimensions when it combines fields: the run stops with a fatal error about inconsistent dimensions in an operation, naming both dimension sets. To convert results back to pascals multiply by the density of the fluid you mean: for a capstone kinematic pressure drop of about 9 × 10⁻⁴ m²/s² (see section 28), air at ρ ≈ 1.2 kg/m³ would give about 1.1 × 10⁻³ Pa. The capstone viscosity 1.0 × 10⁻⁵ m²/s is an illustrative value, close to that of air (≈1.5 × 10⁻⁵) and ten times that of water (≈1.0 × 10⁻⁶); the case is defined by its Reynolds number, not by a specific fluid.

Model fields: with simulationType laminar; the solver reads only U and p. A RAS kEpsilon model adds k, epsilon and nut (with wall functions on walls); kOmegaSST adds k, omega and nut. Extra files left in 0/ by a laminar case are simply not read, which is exactly why they are dangerous: they suggest a turbulence model that is not active.

Each iteration of the steady capstone prints a block like the one below (numbers illustrative). In 2D with empty front and back faces only Ux and Uy are solved: the empty direction has no equation.

Time = 300

smoothSolver:  Solving for Ux, Initial residual = 1.2e-06, Final residual = 9.8e-08, No Iterations 2
smoothSolver:  Solving for Uy, Initial residual = 3.4e-06, Final residual = 2.9e-07, No Iterations 2
GAMG:  Solving for p, Initial residual = 4.1e-06, Final residual = 1.9e-07, No Iterations 3
time step continuity errors : sum local = 2.1e-10, global = -3.5e-12, cumulative = 1.7e-09
ExecutionTime = 1.9 s  ClockTime = 2 s

• Initial residual: the normalised imbalance of the linear system at the start of the solve, i.e. how far the current field is from satisfying the discretised equation. Its trend across iterations is the convergence indicator of a steady run.
• Final residual and No Iterations: how far the linear solver went this time, governed by tolerance and relTol (Part 6). A final residual that never reaches the tolerance is normal with relTol > 0.
• time step continuity errors: the volume-weighted mean of |∇·φ| (multiplied by the time step) after the pressure correction (“sum local”), its signed sum (“global”) and the running total (“cumulative”). Small and non-growing values (≪ 10⁻⁶ in this case) mean the fluxes are mass-conservative.

foamLog log.foamRun            # extracts residual histories into ./logs/
ls logs/                       # Ux_0, Uy_0, p_0, contCumulative_0, ...

foamLog extracts every residual history from a log into separate files that can be plotted; alternatively a residuals function object can write them during the run. A residual plot that falls by several orders of magnitude and then flattens is the typical steady behaviour; a plateau with oscillations calls for the left column of the table above.

Two different questions hide behind “is the result right?”. Verification asks whether the equations are solved correctly: iterative convergence (residuals, continuity) and discretisation error, measured by refining the mesh as in worked case 2 (mesh convergence). Validation asks whether the equations are the right ones for reality, and requires independent data – an experiment, or an exact solution for an idealised case.

The capstone has an exact solution far from the inlet: plane Poiseuille flow. With mean velocity U = 0.01 m/s and height H = 0.020 m the developed profile is u(y) = 6U (y/H)(1 − y/H), with maximum u_max = 1.5U = 0.015 m/s at mid-height, and the kinematic pressure gradient is dp/dx = −12νU/H² = −3.0 × 10⁻³ m/s². Comparing the computed profile at, say, x = 0.25 m with these two numbers is a verification against an analytical solution; the full procedure is in worked case 1 (laminar channel, Poiseuille validation). Low residuals alone would not detect, for instance, a viscosity entered as 1e-4 instead of 1e-5: the run would converge perfectly to the wrong flow.

Work on a copy (cp -r "$FOAM_TUTORIALS/incompressibleFluid/pitzDailySteady" .), even if the exercise is read-only: it removes any risk of touching the installation. For this tutorial, User Guide §2.1 (backward-facing step) and the tutorial files give the answers you should find:

The map is the deliverable in miniature: each row can be checked by someone else in seconds, because it says where the answer comes from.

With writeControl timeStep; a time directory is written whenever the iteration index is a multiple of writeInterval. On the capstone configuration (deltaT 1, endTime 300):

The third row is the kind of difference between prediction and observation that the report asks for: do not assume that the last iteration is always written – check with foamListTimes. Other writeControl values (Part 4) change the meaning of the interval: runTime and adjustableRunTime interpret it as simulated time, cpuTime and clockTime as seconds of computation; purgeWrite N keeps only the last N directories. Because runTimeModifiable true; is set, controlDict is re-read during a run, so an edit made while the solver runs can take effect in mid-run – another reason to edit only disposable copies. If residualControl were present in fvSolution, the run could stop before 300 and change the sequence: that is a second cause, and the constraint above exists precisely to keep causes separate.

Candidate list: foamToC -vectorBCs shows every vector condition; those with “inlet” or “velocity” in their name are the candidates. Three meaningful choices for a channel inlet, each with a different physical statement:

Physical check for the first candidate: the flow rate through the inlet must equal the prescribed value, Q = 2 × 10⁻⁷ m³/s, and the same through the outlet (with opposite sign, because face fluxes are positive outwards). The check is one command (section 28 shows it). Discussion versus fixedValue: fixedValue imposes a vector on each face, including its direction, and the flow rate follows from it; flowRateInletVelocity imposes the flow rate and derives the velocity, always directed into the domain along the face normal, so it stays correct if the patch area or orientation changes. Without a profile both give a uniform inlet velocity in this geometry, so the computed fields should be practically identical – which is itself a useful validation. Interesting further reading: worked case 6 (inlet boundary condition sensitivity).

As in Part 2, independent predictions written in advance are the cheapest error detector available. All values follow from the table:

checkMesh should also report two geometric and two solution directions, (1 1 0): the z direction is removed by the empty patches. Any mismatch between these predictions and the logs points to a specific file.

A note on Stage A: the reference solution (section 23) has four named patches – inlet, outlet, walls (both walls in one patch) and frontAndBack (both empty faces). “Four named physical patch groups” should be read in that sense; splitting the walls into upperWall and lowerWall, as pitzDailySteady does, is equally valid provided the field files follow. A README needs one line per file and nothing more:

step08_channel - README
Purpose      : steady laminar 2D channel, incompressibleFluid, OpenFOAM Foundation 14
0/U          : velocity; inlet fixedValue (0.01 0 0) m/s; walls noSlip; outlet zeroGradient
0/p          : kinematic pressure [m^2/s^2]; outlet fixedValue 0 (reference)
constant/physicalProperties : viscosityModel constant; nu 1e-05 m^2/s
constant/momentumTransport  : simulationType laminar
system/blockMeshDict        : 0.30 x 0.020 x 0.001 m, 80 x 16 x 1 cells, 4 patches
system/controlDict          : solver incompressibleFluid; 300 iterations; write every 50
system/fvSchemes            : steadyState; bounded Gauss upwind for div(phi,U)
system/fvSolution           : GAMG for p, smoothSolver for U, SIMPLE with relaxation
Run          : blockMesh; checkMesh; foamRun
Logs         : log.blockMesh, log.checkMesh, log.foamRun

The configuration-decision record is a table with one row per non-obvious decision, written while you work rather than afterwards:

The interpretation of U, p and the mass balance should state: the maximum velocity and where the profile becomes parabolic; the pressure drop along the channel and its comparison with −12νU/H²; inlet and outlet flow rates and their difference (section 28).

Expected ddtSchemes/default value: steadyState; expected solver value: incompressibleFluid. In the solver log the line “Solving for Uz” must not appear (the empty direction is not solved). If the run finishes but the fields are still uniform at 300, the most likely causes are a field not read from 0/ or an inlet condition that does not prescribe the expected value: go back to the six questions of section 12.

No units or convertToMeters entry is present, so coordinates are read in metres (the SI default; Part 2 uses units [mm]; instead). The vertices are written two per line for compactness: their labels still follow the order in the list, 0 to 7. Vertices 0–3 lie in the plane z = 0, vertices 4–7 in z = 0.001 m, with the pairs 0–4, 1–5, 2–6, 3–7 aligned through the depth. In hex (0 1 2 3 4 5 6 7) the local directions are 0→1 (x, 80 cells), 1→2 (y, 16 cells), 0→4 (z, 1 cell); the mixed product (e₁ × e₂) · e₃ = 0.30 × 0.020 × 0.001 = 6 × 10⁻⁶ m³ is positive, so the block is right-handed and its volume is the volume of the domain. simpleGrading (1 1 1) gives uniform cells, appropriate for a laminar channel at Re = 20 on a first attempt; a refined study could cluster cells towards the walls (Part 2, section on grading).

Each face is given by four vertex labels, ordered so that the right-hand rule gives a normal pointing out of the block (equivalently, clockwise when seen from inside). Verify one: for the inlet (0 4 7 3), (r₄ − r₀) × (r₇ − r₄) = (0, 0, 0.001) × (0, 0.020, 0) = (−2 × 10⁻⁵, 0, 0): pointing to −x, out of the domain. The same calculation gives +x for the outlet (1 2 6 5), −y and +y for the two wall faces, −z and +z for (0 3 2 1) and (4 5 6 7). All six faces of the block are assigned, so no face falls into a default patch.

type wall for the walls is not cosmetic: it marks them for wall-distance calculations and for wall functions if a turbulence model is later selected. type empty tells OpenFOAM that no solution is required in the direction normal to those faces; it is accepted only if the mesh is one cell thick in that direction and both opposite faces are empty, and every field must then use type empty on that patch. mergePatchPairs (); is an empty list, needed only for multi-block meshes with non-conforming interfaces; leaving it in is harmless.

On each open boundary one variable is prescribed (Dirichlet, fixedValue) and the other is left free (Neumann, zeroGradient):

Fixing both U and p at the same boundary over-constrains the problem; leaving both free at all boundaries leaves the pressure level undefined (that is when pRef settings in fvSolution become necessary – not here, because the outlet fixes p = 0). For an incompressible solver only pressure differences matter, so p = 0 at the outlet is a reference, not an atmospheric value. noSlip is equivalent to fixedValue with uniform (0 0 0), written more expressively. The uniform internalField (0.01 0 0) is only the initial guess of the steady iterations. The one-line form inlet { type fixedValue; value uniform (0.01 0 0); } is the same dictionary written compactly (Part 3).

viscosityModel constant; selects a Newtonian fluid with constant kinematic viscosity nu; the official v14 pitzDailySteady uses exactly nu 1e-05;. v14 also accepts a value with explicit units – the User Guide example pitzDailyWater writes nu 1 [cSt]; – which foamUnits can decode. Non-Newtonian alternatives (for example the generalised-Newtonian family that contains BirdCarreau) are covered in Part 7.

simulationType laminar; selects the laminar momentum-transport model, i.e. the Newtonian viscous stress with no turbulence modelling: no further fields are needed. In controlDict, solver incompressibleFluid; tells foamRun which module to load; the time entries make 300 steady iterations (deltaT 1, endTime 300) and write every 50 (writeControl timeStep, writeInterval 50) in ASCII (writeFormat ascii, readable with any editor); runTimeModifiable true re-reads the dictionaries during the run (Part 4).

default none; in divSchemes forces every convection term to be listed explicitly: if one is missing, the solver stops with an error naming the missing key – exactly the term to add. The name div((nuEff*dev2(T(grad(U))))) is the literal expression the code builds for the part of the viscous stress that involves the transposed velocity gradient; for incompressible flow its divergence is formally zero (∇·(∇U)ᵀ = ∇(∇·U)), but it is kept explicitly and must be given a scheme. The official pitzDailySteady uses the same name. On an orthogonal mesh like this one, corrected costs nothing and changes nothing; on a skewed mesh it matters (Part 5).

GAMG (geometric-agglomerated algebraic multigrid) with a GaussSeidel smoother solves the pressure equation, which is symmetric and elliptic: multigrid removes the long-wavelength error that simple smoothers leave behind. smoothSolver with symGaussSeidel is sufficient for the momentum components. relTol 0.05 and 0.1 stop each linear solve once the residual has fallen by that factor: in a steady run, solving each iteration exactly is wasted effort because the coefficients change at the next one. tolerance is the absolute floor.

SIMPLE is the steady pressure–velocity coupling algorithm; nNonOrthogonalCorrectors 0 is right for an orthogonal block mesh. The relaxation factors (p field 0.3, U equation 0.7) are the classic pair for standard SIMPLE, which needs p + U ≈ 1 for stability. The official pitzDailySteady uses the SIMPLEC variant instead: consistent yes; with equation relaxation 0.9 and no field relaxation of p, which usually converges in fewer iterations; it also adds residualControl to stop when residuals reach given values. Either choice is legitimate; what matters is to know which one you are using and why. No pRef entries are needed because p is fixed at the outlet.

Reynolds number. Re_H = 0.01 × 0.020 / 1.0 × 10⁻⁵ = 20. For infinite parallel plates the hydraulic diameter is D_h = 2H = 0.040 m, so Re_Dh = 40; either way the flow is far below any transition threshold (of the order of 10³ for a channel).

Entry length. A widely used correlation for laminar plane-channel flow (Durst et al., 2005) gives L_e/H ≈ 0.631/(1 + 0.044 Re) + 0.0442 Re ≈ 1.2 for Re = 20, i.e. L_e ≈ 0.024 m, about 8 % of the channel length; the rougher estimate 0.05 Re_Dh D_h ≈ 0.08 m is more conservative. In both cases the flow is fully developed well before the outlet, which justifies zeroGradient for U there.

Developed flow. u_max = 1.5 U = 0.015 m/s; kinematic pressure gradient −12νU/H² = −3.0 × 10⁻³ m/s²; over 0.30 m a fully developed estimate of the kinematic pressure drop is 9.0 × 10⁻⁴ m²/s². The computed inlet pressure will be somewhat higher, because the uniform inlet profile must first be reshaped (entrance pressure loss). The upwind scheme on 80 cells adds its own small error – which is exactly what a mesh-refinement study (worked case 2) would quantify.

Mass balance. Q = U H × depth = 0.01 × 0.020 × 0.001 = 2.0 × 10⁻⁷ m³/s. Measure it with the packaged patchFlowRate function object (User Guide 7.2):

foamPostProcess -func "patchFlowRate(name=inlet)" -latestTime
foamPostProcess -func "patchFlowRate(name=outlet)" -latestTime

Expected: about −2.0 × 10⁻⁷ m³/s at the inlet (negative: flux entering) and +2.0 × 10⁻⁷ m³/s at the outlet, with a difference at the level of the continuity errors. If your installation rejects the argument name, run foamGet patchFlowRate and read the copied file for the exact keyword: the guide uses name= on the command line and patch= with #includeFunc.

All directives start with #; macros start with $. User Guide 4.2 documents the language. The listing shows the forms you are most likely to meet in tutorials:

// Examples of directives you may meet (read UG 4.2 before using any of them)
#include        "initialConditions"     // insert another file here
#includeEtc     "caseDicts/setConstraintTypes"
#includeFunc    patchFlowRate(patch=outlet)  // in system/functions
Umean           0.01;
H               0.020;
nu              1e-05;
Re              #calc "$Umean*$H/$nu";   // computed when the file is read
inlet { type fixedValue; value uniform ($Umean 0 0); }

#include inserts a file at that point; #includeEtc takes the file from the OpenFOAM etc directory; #includeFunc loads a packaged function object, with arguments. $Umean substitutes the value of another entry (scoped names such as $../H or $:subDict.key reach other levels). #calc evaluates an expression when the file is read; the #code… family compiles C++ code on the fly, which needs a working compiler and is the hardest to debug – one more reason to use it only when nothing simpler works. Whatever directive is present, this command shows the input the solver will actually receive:

foamDictionary -expand system/controlDict    # shows the values after expansion

A worked example of the protocol, on an object not used in this series: the wallShearStress function object. Category: function object (foamToC -functionObjects); documentation: foamInfo wallShearStress and User Guide 7.2, which shows foamPostProcess -solver incompressibleFluid -func wallShearStress; target: system/functions (or the command line, for a one-off evaluation); check: a wallShearStress field written in the time directories. For the developed capstone flow the expected kinematic wall shear stress is ν · 6U/H = 3.0 × 10⁻⁵ m²/s² on each wall – a quantitative check, not just “it ran”.

The structure of the case does not change: the same three directories, the same dictionaries, the same tools. What changes is the justification behind each value. A practical way to organise the comparison is a two-column audit of the capstone files: