Checking a case¶

The case check finds many of the mistakes that make urbanMicroclimateFoam stop at the start, or compute something other than what the case says (the codes below). Others, such as a misspelt standard OpenFOAM boundary condition type, are not caught yet.

The check reads nothing beyond what opening the case already read, so it is fast enough to run again after every edit.

Run it with umcf-cli check <case> (Command line), or from Rust with umcf_validate::check(&case). The GUI will run it before a run.

Each problem has a level, a code and the file it is about, and where there is one, the region, patch and field:

Boundary conditions against the mesh¶

Every field needs an entry for every patch of its region's mesh. umcfGui picks the entry for a patch the way OpenFOAM does (in both OpenFOAM-8 and 12):

A key written twice (quoted or not) is merged into its first place, entry by entry: a value written only the first time is kept, one written again takes the later value.

1. the entry named after the patch;
2. else an entry named after one of the patch's groups. If several match, the one written last wins. A patch's groups are its inGroups in the boundary file, plus the ones OpenFOAM adds itself:
3. constraint patches (empty, cyclic, symmetryPlane, …) are in the group of their type;
4. wall patches (wall, mappedWall, mappedWallVariableThickness, …) are in wall;
5. mapped patches are in mapped (OpenFOAM-12) or mappedPatch (OpenFOAM-8).

A group with the same name as a patch is ignored, as OpenFOAM does. 3. else nothing, for an empty patch: OpenFOAM gives it empty itself; 4. else a quoted key that is exactly the patch name, else the last quoted pattern that matches the whole patch name, such as "(wall|roof).*". OpenFOAM reads patterns as POSIX extended regular expressions (glibc's, on Linux).

Only field files are checked: files whose class is a field (volScalarField, surfaceScalarField, …). Data tables in a time directory, such as 0/air/Tambient read by a tableFile, are not, and neither are copies the solver never reads (T~, T.orig, T.bak, T.old, …). A type or patchType written as a $macro is not judged. Quoted words (type "empty";) read like plain ones, as in OpenFOAM. Standard OpenFOAM types (fixedValue, inletOutlet, …) are not in the solver catalog, so a misspelt one is not reported yet.

Coupled regions¶

Regions exchange heat and moisture through mapped* patches. The partner comes from neighbourRegion/neighbourPatch (OpenFOAM-12, which still reads the old names) or sampleRegion/samplePatch (OpenFOAM-8).

A patch with a coupleGroup finds its partner by group, so its region and patch names are not checked further.

A meshing step names regions that only exist once the steps are put together, so coupling is checked in solver cases only.

Solver types¶

The model types a region's dictionaries select are checked against the solver catalog for the case's OpenFOAM version. This covers vegetationModel, grassModel, solarLoadModel, the solar absorption and scattering models, and buildingMaterialModel. They are checked where the solver reads them: - the top level of vegetationProperties, grassProperties and solarLoadProperties; - each entry of the buildingMaterials ( { … } ) list in transportProperties.

These files sit directly in constant/<region>/ (or constant/). Other files, such as vegetationProperties.orig or a nested alternatives { … }, are left alone. A selector written twice counts once, with its last value.

Fields the solver reads¶

Every region needs the fields the solver reads for its kind of region, and the fields the models selected there read. A missing one stops the run at the start. The list comes from the solver source, per version (Solver coverage), plus what OpenFOAM itself reads for what the solver sets up:

Notes: - Fields read only if present (phi, Tl, Tg) are not required. - Files the radiation utilities write (F, finalAgglom, …) are covered by the script checks. - A model can read different fields in each of its constructors. Only the constructors the solver builds it with count (it builds solarLoadModel from a field, so directAndDiffuse needs qs, not the Qs its dictionary constructor reads). A read in a member function, which may never run, is not required.

Field sizes¶

A nonuniform internalField has one value per cell of a volume field (vol…Field), per internal face of a surface field (surface…Field) and per point of a point field (point…Field). OpenFOAM stops on any other length. The check compares the list's length with the counts in the owner header of the mesh the run reads, which OpenFOAM writes there (nPoints:… nCells:… nFaces:… nInternalFaces:…): the region's mesh in the latest time directory up to the start time that has one (meshing without -overwrite writes one), else the one in constant. A mesh without that note is not checked.

Keywords the selected models need¶

The vegetation, grass, solar load and radiation model selected in a region's dictionary (vegetationProperties, grassProperties, solarLoadProperties, radiationProperties) reads its coefficients from <Type>Coeffs in the same file. The keywords it reads with lookup whenever the solver builds it must be there. Those are the keywords read in the constructors the solver uses, or in a function each of them calls, outside any condition (a block run only on the master process counts: every run has one) (Solver coverage). For example, simplifiedVegetation needs a1, a2, a3, C, D0, H, kc, l, nEvapSides, Rg0, Rl0 and rsMin, and viewFactorSky needs smoothing and constantEmissivity.

A dictionary whose entries can come from elsewhere (#include, $macro) or match by pattern ("a.*") is not judged.

Regions and run controls¶

Values written as $macros are not judged.

Scripts¶

The case's scripts (Allprepare, Allrun, Allclean, *.sh and batch job files) are read as described in The case workflow and checked against the case and its OpenFOAM version. Each problem names the script and line.

Finite-volume constraints and pressure limits (OpenFOAM-12)¶

Tested on¶

The check runs on the local reference cases: the Hong Kong project's meshing chain and runs, the 3×3 test cases and the large parallel cases, in OpenFOAM-8 and 12. These cases ran, so every error there must be real. Those found: - the solid-initialisation run of the Hong Kong project starts from its latest time, which has no air fields, so running it again would fail; - a 3×3 case ported to OpenFOAM-12 ends its Allrun with reconstructPar -allRegions and has no regionSolvers; its fvConstraints also hides the fvOptions with the air's temperature limit; - the large 3×3 cases (OpenFOAM-12) clean with foamCleanPolyMesh, which OpenFOAM-12 doesn't have.