What a case needs¶

Everything an urbanMicroclimateFoam case needs to run: its regions and their names, the dictionaries and fields of each region, the coupling between them, the meshing chain from STL surfaces, and the radiation and weather inputs. This is the specification umcfGui builds new cases against (gaps lists what it can build and check so far).

It is drawn from the solver source (solver/, the pinned commit and the of-org_v8.0 tag), the UMCF tutorials (windAroundBuildings_CFDHAM_veg for the chain from STL surfaces, streetCanyon_CFDHAM for radiation without trees) and the reference cases. Source lines are given as file:line in solver/. R marks what a run or utility stops without; 8 and 12 mark differences between OpenFOAM-8 and OpenFOAM-12. Points not confirmed by a run are marked unconfirmed.

Regions¶

The regions are listed in system/controlDict 12 (regions { fluid (air); solid (…); vegetation (…); }, plus regionSolvers with the same regions for the -allRegions utilities) or in constant/regionProperties 8 (regions ( fluid (air) solid (…) vegetation (…) );).

Radiation runs in one region:

• without trees, in air itself: constant/air/radiationProperties, constant/air/solarLoadProperties, the view factor dictionary, and 0/air/qr, 0/air/qs;
• with trees, in vegetation, whose patch air_to_vegetation is the canopy surface (simplifiedVegetation.C:323): mappedInternal 12, mappedWall with sampleMode nearestCell; sampleRegion air; 8. Radiation is not solved in air then.

Dictionaries per region¶

A region without radiationProperties has no radiation, and one without solarLoadProperties no solar load; the solver doesn't stop.

Materials and cell zones. Every buildingMaterials name must be a cell zone of that solid region, and the zones must cover every cell exactly once (solid/updatebuildingMaterials.H). The zones come from topoSet 12 or setSet -batch 8.

What the equations read.

• Air fvSolution: solvers for p_rgh and (U|k|epsilon|w|h|e); SIMPLE with nNonOrthogonalCorrectors and residualControl; relaxationFactors for fields and equations. With simplifiedVegetation, relaxationFactors and SIMPLE/residualControl are R (simplifiedVegetation.C:303-306).
• Air fvSchemes: ddt steadyState, the div schemes for U, e (or h), K, Ekp 12, k, epsilon and w, and the stress term.
• Solid fvSolution: solvers for pc and Ts. Solid fvSchemes: ddt Euler and laplacian(Krel,pc) (every laplacian of the solid equations has that name).

Run controls (system/controlDict, all with defaults): the solid sub-stepping (initialSolidTimestepFactor, minDeltaT, maxDeltaT, the Picard tolerances), the fluid iterations (minFluidIteration, maxFluidIteration), viewFactorWorkflow (sparse or dense; read from controlDict before the model's coefficients), and blending with blendingCoeffs for meso-scale nudging. deltaT is the fluid and radiation step; the solids step inside it.

Fields¶

Tables that are not fields: 0/air/Tambient and 0/air/wambient (outdoor temperature and humidity ratio), 0/air/cloudCover, 0/<solid>/T_room.dat (indoor temperature). See time and weather.

Boundary conditions by patch role¶

air:

p is calculated, and slip on the sides and top; gcr is fixedValue, and slip on the sides and top. The inlet's U, k and epsilon take the profile (Uref, Zref, zDir, flowDir, z0, zGround), usually from an included ABLConditions. Other inlets the tutorials use: turbulentIntensityKineticEnergyInlet with turbulentMixingLengthDissipationRateInlet, and readVectorField for a meso-scale wind with blending.

Solid:

The radiation region (vegetation, or air without trees):

The solid temperature conditions take qr and qs at the first iteration and then every 600 s of simulated time.

Coupling rules¶

1. Patch types. The CFDHAM conditions and mappedValue need a mapped patch; mappedLeafTemperature needs mappedInternal 12.
2. Pairs. An air wall coupled to a solid is mappedWall with neighbourRegion <solid>; neighbourPatch <solid patch>; and the solid patch is mappedWall back to air (8: sampleMode nearestPatchFace; sampleRegion; samplePatch;). How the faces are paired: 12 with method nearest (the reference cases) by the nearest face; without method (the STL tutorial) OpenFOAM takes the patches to be conformal and pairs them with an octree (mappedPatchBase.H:36-41); intersection weights by overlap; 8 nearestPatchFace.
3. Radiation reaches the solids by name. With a vegetation region, the solid temperature condition reads qr and qs from the vegetation patch named like the air patch it is coupled to (CFDHAMsolidTemperatureCoupledMixed…C:351, and the same in CFDHAMsolidTemperatureTransferCoeff). So every air patch coupled to a solid needs a patch of the same name in vegetation. Without trees, it reads them from the air patch.
4. Sky or surface. In the radiation region, every patch that is not a surface is sky: the surfaces are wall patches, and mappedInternal ones 12 (viewFactorSky.C:1294-1298; 8 tests wall only). So the domain sides and top are patch or mapped (mappedPatch 8), the ground and buildings wall or mappedWall. Patches with a fixed-value-derived qr take part in the view factors; the view factor dictionary sets how coarse each is (nFacesInCoarsestLevel). A patch without an entry isn't agglomerated: it keeps every face, which costs time and memory but doesn't stop the run.
5. The vegetation region's patches are mapped (mappedPatch 8, sides and top) or mappedWall (ground and buildings) to the same-named air patch, and air_to_vegetation is mappedInternal with offsetMode normal; distance 0; 12, mappedWall with sampleMode nearestCell; sampleRegion air; 8.

Meshing from STL surfaces¶

Real cases mesh in one of three ways:

• block regions (the 3×3 reference cases): the buildings are missing blocks of a multi-block blockMeshDict, and each solid is a blockMesh of its own;
• from STL surfaces (the windAroundBuildings_CFDHAM_veg tutorial): one background box, snappyHexMesh cuts the buildings out of the air, and the solids are extruded from the building surface and the ground;
• conformal solids: as above, but each solid is extruded from the snapped air patch (written out as a surface), so solid and air meet face for face.

The chain from STL surfaces, 12:

8 (the tutorial's of-org_v8.0 tag): buildings only (no ground region), one extrusion layer, setSet -batch, sampleMode nearestPatchFace.

Names that must agree across the steps:

Radiation¶

Inputs¶

These tables are read through a file path, not as OpenFOAM objects, so cargo xtask catalog doesn't list them in solver coverage.

The chain¶

Run per processor once the case is decomposed, in this order:

solarRayTracingGen needs kcLAIboundary whenever the region list has a vegetation region, with one entry per sun position. calcLAI reads the <model>Coeffs dictionary of the vegetation model (calcLAI.C:566), so vegetationModel none needs an empty noneCoeffs. Unconfirmed: whether a vegetation region without trees then runs with calcLAI, vegetationModel none and a zero LAD.

Time and weather¶

The solver has no calendar: every table is keyed by simulation time in seconds. In the reference cases t = 0 is local midnight of the simulated day, endTime 86400 and deltaT 3600 give an hourly day. The date, the site (latitude, longitude, time zone) and the mesh's north exist only where the tables were made, so a GUI that builds a case keeps them itself and writes sunPosVector, IDN, Idif (and Tambient, wambient, cloudCover, LW) from them.

The tables interpolate linearly and hold their last value past the end: a table that ends before endTime goes on silently with its last value. Every table should cover the run and share its time base.

OpenFOAM-8 and OpenFOAM-12¶

More on telling and porting the two: OpenFOAM versions.