Overset meshes

Example 1. Overset cylinders

Four meshes make up this case: a coarse background, a finer refinement region over it, and a mesh round each of two cylinders over that.

Step 1. Download the files

The bundle can be downloaded here.

cd ~
wget https://zcfd.zenotech.com/v2026.11.16174/tutorial_5_overset_cylinders.tgz
tar xzf tutorial_5_overset_cylinders.tgz
cd tutorial_5_overset_cylinders

It contains the control file overset_cylinders.py and three meshes: background.h5, refinement_region.h5 and cylinder.h5, which both cylinders use.

Step 2. Walk through the input

The control file, overset_cylinders.py, is a short Python script. All it does is build one Python dictionary, called parameters, that tells zCFD everything about the run: the physics, the numerical method, what to write out, and the mesh with its boundaries. This step walks through that dictionary from top to bottom. Each heading below is the name of a key, written exactly as it appears in the file, and the headings nest the same way the dictionary does: numerical scheme, for example, sits inside solver. Under each heading you'll find what that part controls, what each setting means, and why it has the value it has here. Each section ends with a link to that part's reference page, which lists every setting it accepts and its default; you don't need it to follow the tutorial. On a wide screen the whole control file sits on the right, with the part being described highlighted as you scroll.

Here model has one entry for each of the four meshes.

parameters = {
    "config version": 2,
    "solver": {
        "solver settings": {"type": "compressible"},
        "equations": {"type": "viscous", "precondition": True},
        "fluid properties": {
            "material": "air",
            "gamma": 1.4,
            "gas constant": 287.0,
            "sutherlands const": 110.4,
            "prandtl no": 0.72,
            "turbulent prandtl no": 0.9,
        },
        "reference conditions": {
            "IC_1": {
                "temperature": 277.7777,
                "pressure": 101325.0,
                "v": {"vector": [1.0, 0.0, 0.0], "mach": 0.2},
                "reynolds no": 20.0,
                "reference length": 1.0,
            }
        },
        "initialisation": {"initial conditions": "IC_1"},
        "numerical scheme": {"order": "second"},
        "time settings": {"type": "steady"},
        "convergence control": {
            "scheme": {"name": "implicit euler", "stage": 1},
            "cfl": {
                "cfl": 20,
                "cfl viscous factor": 1.0e-6,
                "cfl ramp": [{"type": "exponential", "factor": 1.05, "initial": 0.1}],
            },
            "cycles": 2000,
        },
        "output settings": {
            "report": {
                "frequency": 5,
                "monitor": {
                    "MR_1": {
                        "name": "probe",
                        "point": [1.07, 0.25, 0.313],
                        "variables": ["cp"],
                    }
                },
            },
            "solution": {
                "format": "vtk",
                "surface variables": ["V", "p", "T", "rho", "cp"],
                "volume variables": ["V", "p", "T", "rho", "mach", "cp", "overset"],
            },
        },
    },
    "model": {
        "background": {
            "mesh": "background.h5",
            "transforms": {
                "transform": [
                    [1.0, 0.0, 0.0, 0.0],
                    [0.0, 1.0, 0.0, 0.0],
                    [0.0, 0.0, 1.0, -0.5],
                    [0.0, 0.0, 0.0, 1.0],
                ]
            },
            "boundary conditions": {
                "BC_1": {"zones": [9, 11], "type": "symmetry"},
                "BC_2": {
                    "zones": [10],
                    "type": "farfield",
                    "condition": "IC_1",
                    "kind": "riemann",
                },
            },
        },
        "refinement_region": {
            "mesh": "refinement_region.h5",
            "boundary conditions": {
                "BC_1": {"zones": [9, 11], "type": "symmetry"},
                "BC_2": {
                    "zones": [10],
                    "type": "interface",
                    "kind": "overset",
                    "connection": {"model": ["background"]},
                    "additional active layers": 3,
                },
            },
        },
        "cylinder_2": {
            "mesh": "cylinder.h5",
            "transforms": {
                "transform": [
                    [1.0, 0.0, 0.0, 0.0],
                    [0.0, 1.0, 0.0, -0.8],
                    [0.0, 0.0, 1.0, 0.0],
                    [0.0, 0.0, 0.0, 1.0],
                ]
            },
            "boundary conditions": {
                "BC_1": {"zones": [11, 12], "type": "symmetry"},
                "BC_2": {
                    "zones": [13],
                    "type": "interface",
                    "kind": "overset",
                    "connection": {"model": ["refinement_region"]},
                    "additional active layers": 3,
                },
                "BC_3": {"zones": [10], "type": "wall", "kind": "no slip"},
            },
        },
        "cylinder_1": {
            "mesh": "cylinder.h5",
            "transforms": {
                "transform": [
                    [1.0, 0.0, 0.0, 0.0],
                    [0.0, 1.0, 0.0, 0.8],
                    [0.0, 0.0, 1.0, 0.0],
                    [0.0, 0.0, 0.0, 1.0],
                ]
            },
            "boundary conditions": {
                "BC_1": {"zones": [11, 12], "type": "symmetry"},
                "BC_2": {
                    "zones": [13],
                    "type": "interface",
                    "kind": "overset",
                    "connection": {"model": ["refinement_region"]},
                    "additional active layers": 3,
                },
                "BC_3": {"zones": [10], "type": "wall", "kind": "no slip"},
            },
        },
    },
}

config version

"config version": 2 says which layout of the control file this is. It may be written with a space or an underscore.

solver

solver holds the settings shared by all four meshes.

solver settings

solver settings chooses the solver.

• type: compressible, the density-based solver.

equations

equations sets which equations are solved.

• type: viscous, the laminar Navier–Stokes equations; the flow round each cylinder is laminar at a Reynolds number of 20. The Reynolds number compares the flow's inertia with its viscosity.
• precondition: True, low-Mach-number preconditioning, recommended below about Mach 0.3.

fluid properties

fluid properties describes the gas.

• material: air, an ideal gas, with gamma 1.4 and gas constant 287.0 J/kg/K.
• sutherlands const: 110.4 K, for the viscosity's change with temperature.
• prandtl no 0.72 and turbulent prandtl no 0.9; the turbulent one plays no part in a laminar run.

reference conditions

reference conditions defines named flow states.

IC_1

IC_1 is the freestream.

• temperature 277.7777 K and pressure 101325 Pa.
• v: vector [1, 0, 0] and mach 0.2, so the flow runs along +x at 66.8 m/s.
• reynolds no: 20, based on the reference length, 1.0 m, the diameter of each cylinder. Above a Reynolds number of about 47, a single cylinder sheds vortices: they peel off alternately behind it, so the flow never settles to a steady state. Two cylinders 1.6 diameters apart behave more like one wider body, so they start to shed sooner; 20 is chosen to stay below that, so the flow settles to a steady state. The run confirms it by converging.

initialisation

initialisation sets the starting state.

• initial conditions: IC_1 in every cell of every mesh.

numerical scheme

numerical scheme sets the spatial discretisation.

• order: second, with the default Roe flux and van Albada limiter. Choosing a limiter covers both.

time settings

time settings says how the run advances.

• type: steady. The flow at this Reynolds number does not change in time, so the solver simply iterates, in a made-up pseudo-time, until the solution stops changing. Choosing a time-marching scheme explains the choice.

convergence control

convergence control sets how the pseudo-time iterations converge to the steady state.

scheme

• name: implicit euler. An overset case needs an implicit pseudo-time scheme; see Practical consequences.
• stage: 1. It has no effect under implicit Euler, which has only one stage.

cfl

• cfl: 20, the pseudo-time CFL number. This overset stack diverges in its first cycles at 100 or more.
• cfl viscous factor: 1.0e-6. It scales the viscous part of each cell's pseudo-time step estimate, so at this value the convective wave speeds alone set the step.
• cfl ramp: starts at 0.1 and grows by 1.05 a cycle, so the first cycles, from a flow that has not yet seen the cylinders, are gentle.

cycles

• cycles: 2000, enough for the residuals, which measure how far the equations are from being satisfied, to fall several orders of magnitude, and for the probe to settle.

output settings

output settings sets the report, written as the run goes, and the solution files. Each model gets its own report and solution files, in its own folder.

report

• frequency: a row every 5 cycles in each model's report, with that model's residuals.
• monitor: MR_1, named probe, records cp at the point [1.07, 0.25, 0.313], between and behind the cylinders. Every model's report has the column probe_cp, but only the model whose active cell holds the point fills it: here the refinement region. In the others it stays zero.

solution

• format: vtk, VTK HDF files for ParaView.
• surface variables: V, p, T, rho and cp on each model's boundaries.
• volume variables: the same, with mach, and overset: 0 in a cell another mesh has taken over, 1 in a cell that is active, and 2 in a cell kept active only by additional active layers, in the band where two meshes overlap. Step 5 uses it to show only the active cells.
• With no frequency set, the solution files and the checkpoint are written once, at the end of the run.

model

model has one entry for each mesh. Each name, such as background, names that model's output folder, overset_cylinders_OUTPUT/background/, and its files. The order matters: each mesh oversets meshes before it in the list. background is walked in full below; the others differ only as each says.

background

The coarse mesh beneath the others, 100 m square.

mesh

background.h5, 10,000 cells.

transforms

transforms places the mesh when it is read.

• transform: a 4 × 4 matrix whose last column translates the mesh. Here it moves the mesh 0.5 m down z, so that its span, built from z = 0.5 to 1.5, lines up with the other meshes' span, z = 0 to 1. Placing and moving a mesh describes the matrix.

boundary conditions

boundary conditions assign a condition to each group of the mesh's zones.

BC_1

• zones [9, 11], the two faces normal to the span, type symmetry, so one cell across the span is enough.

BC_2

• zones [10], the outer boundary, type farfield with condition IC_1 and kind riemann.

refinement_region

A finer Cartesian mesh round both cylinders, 12,800 cells in refinement_region.h5, with no transform.

boundary conditions

Its BC_1 is the same symmetry. Its BC_2 is where it meets the background:

BC_2

• zones: [10], the outer boundary of the refinement region.
• type interface and kind overset: the boundary of an overset mesh. The background cells that lie under the refinement region are not solved, and the two meshes exchange the solution across this boundary.
• connection: model ["background"], the mesh it takes its data from. Naming it tells the solver exactly which pair of meshes to map; without it, the solver maps against every model before this one.
• additional active layers: 3. The hole the refinement region cuts in the background would otherwise match its own outline exactly, leaving no band where both meshes are solved, and the interface faces would find no active cell to take their data from. Three extra layers of background cells are kept active round the hole, so the two meshes overlap. Donor search explains why this matters.

Overset interface lists its other settings.

cylinder_2

The lower cylinder: cylinder.h5, 5040 cells round a cylinder of 1 m diameter.

• transforms: transform moves it 0.8 m down y.
• BC_1: symmetry on zones [11, 12].
• BC_2: an overset interface on zone 13, its outer boundary, with connection model ["refinement_region"] and, for the same reason as the refinement region's, additional active layers 3.
• BC_3: zone 10, the cylinder surface, a no-slip wall.

cylinder_1

The upper cylinder: the same mesh and conditions as cylinder_2, moved 0.8 m up y instead. One mesh file can serve several models, each placed by its own transform.

The two cylinder meshes overlap each other between the cylinders. That is allowed, because each names its own donor, the refinement region; in each place the solution is taken from the topmost mesh.

Step 3. Run

In the activated environment, check the control file and run it:

cd ~/tutorial_5_overset_cylinders/
validate_input overset_cylinders.py
run_zcfd -c overset_cylinders.py

All four meshes are read from the mesh key of each model. These are extracts from the log of a run of this tutorial, overset_cylinders.log, with ... marking lines left out:

Parameters validated successfully
...
 Reading file background.h5
 Global Mesh Stats: Cells: 10000 Faces: 40200
...
 Reading file refinement_region.h5
 Global Mesh Stats: Cells: 12800 Faces: 51440
...
 Reading file cylinder.h5
 Global Mesh Stats: Cells: 5040 Faces: 20280
...
Overset hole cut: blanked 168 background cells enclosed by the hole (inside the overset mesh's solid bodies)
...
Overset mapping: 104 of 288 (36.1111%) background halo centres found no active donor cell in the overset mesh. Those faces fall back to the unmapped face treatment instead of interpolated data. The meshes do not overlap deeply enough: increase 'additional active layers' on the overset interface.
...
============================================================
 Overset Mesh Hierarchy (4 models, 6 pairs)
============================================================
 background                  [root]
 └── refinement_region       [overset]
     ├── cylinder_2              [overset]
     └── cylinder_1              [overset]
 Peer overlaps: background ↔ cylinder_2, background ↔ cylinder_1, cylinder_2 ↔ cylinder_1
============================================================
...
 Solve Complete: 2000 cycles in 2m 27.7s (avg 73.8 ms/cycle)
...
zCFD finished: all requested cycles are complete (2000 in total).

• Each mesh is read in turn; cylinder.h5 is read twice, once for each cylinder.
• The hole cut blanks the background cells inside each cylinder.
• The hierarchy shows which mesh oversets which, as the connection entries ask.
• As the run goes, a report box every few cycles gives each model's residuals separately.
• The log may print a few lines starting Overset mapping:. Each reports the share of an interface's halo cells, the extra cells along the interface that hold the other mesh's values, that found no active donor cell to take data from; those faces use the unmapped-face treatment instead of interpolated data. They are diagnostics, not errors. The three additional active layers set above reduce them, and this case converges cleanly with the few that remain. Donor search explains these lines.
• The run ends after its 2000 cycles.

Output files

Each model folder holds files named after the model, such as cylinder_1/cylinder_1_report.csv and cylinder_1/cylinder_1.vtkhdf.

Step 4. Monitor

Open the run in zMon:

zmon overset_cylinders.py

zMon shows each model's residuals and monitors against cycle; Monitoring a run describes the panels.

• Each model has its own residuals. The cylinder meshes start with the largest, as the flow first meets the cylinders, and fall more than four orders of magnitude. The refinement region starts from the uniform freestream, so its residual starts near zero, rises as the disturbance reaches it, then falls. The background's residual stays at round-off level, around 10^-18, throughout.
• The probe_cp monitor sits in the wake between and behind the cylinders. Choose the refinement region's report: it is the mesh whose active cell holds the point, and the other models show zero. Once the run has converged the probe holds a steady value.

Step 5. Post-process

First activate your zCFD environment, which provides Python with zutil, h5py and ParaView:

source <ZCFD_INSTALL_PATH>/bin/activate

Python

This script prints each model's largest and final density residual, and the final value at the probe. Save it as print_convergence.py beside the control file:

from zutil.fileutils import get_zcfd_result

result = get_zcfd_result("overset_cylinders.py")
for model, report in result.model_reports.items():
    rho = report.data["rho"]
    print(f"{model}: density residual fell from {rho.max():.1e} to {rho.iloc[-1]:.1e}")
probe = result.model_reports["refinement_region"].data["probe_cp"]
print(f"probe cp at the end of the run: {probe.iloc[-1]:.3f}")

python print_convergence.py

ParaView

Overset meshes keep their solutions separate, so you can load only the meshes covering the region you want. To view the whole domain as one, combine them in ParaView:

• Load the four files overset_cylinders_OUTPUT/background/background.vtkhdf, .../refinement_region/refinement_region.vtkhdf, .../cylinder_1/cylinder_1.vtkhdf and .../cylinder_2/cylinder_2.vtkhdf.