8  Running Wake CFD

Binaries, input-file composition, and parallel execution

8.1 Overview

Wake CFD executes cases from JSONC configuration files. Pass one input file to the solver binary; the solver reads mesh files, applies the configuration, and writes outputs to the working directory.

8.2 Basic execution

Wake CFD provides dimension-specific solver binaries. Use wake_2d_mixed for 2D cases and wake_3d_mixed for 3D cases. The binary dimension must match analysis.dimension in the input file.

Linux:

./wake_2d_mixed case.jsonc  # for analysis.dimension: 2
./wake_3d_mixed case.jsonc  # for analysis.dimension: 3

Windows PowerShell:

& "C:\Program Files\Wake CFD\bin\wake_2d_mixed.exe" case.jsonc
& "C:\Program Files\Wake CFD\bin\wake_3d_mixed.exe" case.jsonc

The executable also selects compile-time precision; it is not an input-deck key.

Suffix State / residual / flux arithmetic Linear system Intended use
_fp64 Double precision Double precision throughout Numerical reference and CPU/GPU comparisons.
_mixed Double precision Preconditioner and the matrix copy it runs on in FP32; the outer Krylov iteration stays double Production default.
_fp32 Float: the residual path and the solution and residual arrays alike FP32 Speed-oriented runs with a higher residual floor.

Geometry coordinates, physical time, and the values written to output and restart files are double in every tier.

For example, wake_3d_fp64 and wake_3d_mixed accept the same 3D deck. Available binaries depend on the installed build. Windows uses the same names with .exe. The removed expert_parameters.krylov.precision key cannot change executable precision. For DBNS FP32, nondimensional input is recommended; use monitored quantities to assess convergence when residuals reach their precision floor. The FP32 binary warns when run_control.convergence.residual_absolute is below -6, which is where the FP32 flux evaluation bottoms out. It also rejects any material that is not a calorically perfect gas — eos.type: "peng_robinson" and NASA-polynomial specific heat among them — because a real-gas law evaluated in float loses 1e-3 to 2e-2 relative accuracy. Run those cases with the mixed or FP64 binary.

Executing wake_2d_mixed with analysis.dimension: 3 (or vice versa) triggers a dimension mismatch error.

8.3 Command-line options

Wake CFD CLI accepts options to override settings, validate input, and control execution behavior. The list below is the solver’s own --help output.

Option Description Example
--overlay <file> Apply JSON Merge Patch (RFC 7396) --overlay mach-085.json
--patch <file> Apply JSON Patch (RFC 6902) --patch changes.json
--iter <N> Override iteration count --iter 500
--max-iter <N> Alias for --iter --max-iter 1000
--restart <dir\|file> Continue a previous run; see below --restart out/
--device <N> Pin to GPU device N (single-rank only) --device 0
--license <file\|port@host> Use this license instead of the usual lookup --license 27000@lic01
--validate Validate input and exit without execution --validate
--format json With --validate, emit one JSON result to stdout --validate --format json
--capabilities Print the binary’s own profile as JSON and exit --capabilities
--export-schema [dir] Export JSON schemas and exit --export-schema docs/
--grpc <port\|auto> Start gRPC runtime control server --grpc auto
-h, --help Show help and exit --help

A CUDA build lists --device; a CPU build does not, so that a build never advertises a flag it would silently ignore. --format json is read only alongside --validate. --export-schema takes an optional directory and writes to docs/input when none is given. An unrecognized --option is a warning, not an error: the run continues without it, so check the log when a flag appears to have no effect.

Resuming a run: --restart takes either a directory, in which case the solver picks the latest restart_flow_*.wsol inside it, or one .wsol file. It injects initialization.restart and run_control.resume: true into the composed configuration, so no edit to the input file is needed.

Iteration override: --iter (or --max-iter) overrides run_control.iteration for one execution without modifying the input file. Use this to verify case setup before committing to the configured iteration count.

Linux:

./wake_3d_mixed case.jsonc --iter 100

Windows PowerShell:

& "C:\Program Files\Wake CFD\bin\wake_3d_mixed.exe" case.jsonc --iter 100

For environment-variable configuration (logging, MPI behavior), see Environment variables. For convergence criteria, CFL policy, and unsteady time stepping, see Run control and convergence.

8.4 Input-file composition

Wake CFD supports configuration inheritance and runtime overrides, allowing cases to share common settings and apply targeted changes without duplicating entire input files.

8.4.1 Starter template

Wake CFD provides a canonical JSONC template at user-interfaces/cli/wake_template.jsonc. This template includes all major configuration blocks with sensible defaults for a 3D compressible Euler case.

Template structure:

{
  "mesh": [{ "file_name": "mesh.cgns", "format": "cgns" }],
  "analysis": { "time": "steady", "solver": "dbns", "dimension": 3 },
  "models": { "type": "euler", "regime": "compressible" },
  "materials": [{ "name": "Air", "type": "pure", "eos": {...} }],
  "reference": { "pressure": 101325.0, "temperature": 273.15, ... },
  "domains": [{ "name": "fluid", "boundaries": [...] }],
  "numerical_method": { "dbns": {...}, "linear_solver": {...} },
  "initialization": { "type": "auto" },
  "run_control": { "iteration": 1000, "convergence": {...} },
  "outputs": { "restart": {...}, "volumes": [...] },
  "monitoring": { "history_files": [...], "console": {...} }
}

The outline above omits four optional top-level blocks the solver also accepts: interfaces, expressions, expert_parameters, and wake_version (informational, logged only). Unknown keys are rejected with the offending JSON path, so a typo stops the run instead of defaulting silently.

Start from this template and modify only the settings relevant to your case. For complete field definitions, see CLI configuration-file reference.

8.4.2 $extends (inheritance)

Concept: Inherit configuration from a base file and write only the differences. This avoids duplicating unchanged settings across parameter sweeps or configuration variants.

Scenario: Run the same wing geometry with different Mach numbers.

Step 1: Create base configuration (case.jsonc):

{
  "mesh": [{ "file_name": "wing.cgns", "format": "cgns" }],
  "analysis": { "time": "steady", "solver": "dbns", "dimension": 3 },
  "models": { "type": "euler" },
  "materials": [{ "name": "Air", "eos": { "type": "ideal_gas" } }],
  "domains": [{
    "name": "fluid",
    "material": "Air",
    "boundaries": [
      { "name": "wall", "type": "wall", "mesh_markers": ["WING"] },
      { "name": "farfield", "type": "farfield", "mesh_markers": ["FARFIELD"],
        "mach": 0.7, "pressure": 101325.0, "temperature": 273.15,
        "aoa": 2.0 }
    ]
  }],
  "numerical_method": { "dbns": { "convective": { "scheme": "roe" } } },
  "run_control": { "iteration": 3000 }
}

Step 2: Create variant with $extends (mach-08.jsonc):

{
  "$extends": "case.jsonc",
  "domains": [{
    "name": "fluid",
    "material": "Air",
    "boundaries": [
      { "name": "wall", "type": "wall", "mesh_markers": ["WING"] },
      { "name": "farfield", "type": "farfield", "mesh_markers": ["FARFIELD"],
        "mach": 0.8, "pressure": 101325.0, "temperature": 273.15,
        "aoa": 2.0 }
    ]
  }]
}

Step 3: Execute the variant:

Linux:

./wake_3d_mixed mach-08.jsonc

Windows PowerShell:

& "C:\Program Files\Wake CFD\bin\wake_3d_mixed.exe" mach-08.jsonc

A far field in this form carries four required inputs — mach, pressure, temperature, and a direction, given either as aoa (with optional aos) or as the flow_direction unit vector. An incomplete boundary is rejected before the run starts rather than defaulting silently.

The solver merges mach-08.jsonc onto case.jsonc before execution. Because arrays are replaced, the variant repeats the complete domain and boundary array while changing Mach. Settings outside that array inherit from the base. Use --patch below to change a single array element without repeating it.

Inheritance chain: $extends can reference another file that also uses $extends, creating a multi-level inheritance hierarchy. The solver resolves the chain from base to leaf, applying each layer in order.

Relative paths: Paths in $extends are relative to the file containing the $extends directive, not the working directory.

8.4.3 --overlay (Merge Patch, RFC 7396)

Concept: Apply a JSON Merge Patch (RFC 7396) to override settings without editing the input file. Objects are deep-merged; arrays are replaced entirely.

RFC 7396: IETF standard for partial JSON modification. Objects merge recursively; arrays replace completely; null deletes a key.

Scenario: Override Mach number and iteration count for a quick smoke test without modifying case.jsonc.

Overlay file (mach-085.json):

{
  "domains": [{
    "name": "fluid",
    "material": "Air",
    "boundaries": [
      { "name": "wall", "type": "wall", "mesh_markers": ["WING"] },
      { "name": "farfield", "type": "farfield", "mesh_markers": ["FARFIELD"],
        "mach": 0.85, "pressure": 101325.0, "temperature": 273.15,
        "aoa": 2.0 }
    ]
  }],
  "run_control": {
    "iteration": 500
  }
}

Execution:

Linux:

./wake_3d_mixed case.jsonc --overlay mach-085.json

Windows PowerShell:

& "C:\Program Files\Wake CFD\bin\wake_3d_mixed.exe" case.jsonc --overlay mach-085.json

The overlay deep-merges into the loaded configuration. In this example: - The farfield boundary’s mach changes to 0.85 - run_control.iteration changes to 500 - All other settings remain unchanged

Array replacement: Merge Patch replaces entire arrays. If case.jsonc defines three boundaries and the overlay defines one boundary array with one item, the result contains only that one boundary. To modify individual array items without replacing the entire array, use --patch instead.

Use cases: - Parameter sweeps (vary Mach, angle of attack, CFL) - Quick convergence tests (reduce iteration count) - Execution-time configuration (change output frequency, disable restarts)

8.4.4 --patch (JSON Patch, RFC 6902)

Concept: Apply a JSON Patch (RFC 6902) to modify specific fields using path-based operations. This allows precise edits to array items and nested objects without replacing entire structures.

RFC 6902: IETF standard for expressing operations on JSON documents. Supports add, remove, replace, move, copy, and test.

Supported operations:

Operation Description Use case
add Insert or append an item at a path Add a boundary condition, append a material
remove Delete the item at a path Remove a domain, delete an output
replace Change the value at a path Update Mach number, change iteration count
move Relocate an item from one path to another Reorder boundaries
copy Duplicate an item to another path Clone a material definition
test Assert that a path has a specific value Validate dimension before applying patch

Scenario: Change the Mach number of the second boundary in the first domain and update the iteration count.

Patch file (changes.json):

[
  { "op": "replace", "path": "/domains/0/boundaries/1/mach", "value": 0.85 },
  { "op": "replace", "path": "/run_control/iteration", "value": 1000 }
]

Execution:

Linux:

./wake_3d_mixed case.jsonc --patch changes.json

Windows PowerShell:

& "C:\Program Files\Wake CFD\bin\wake_3d_mixed.exe" case.jsonc --patch changes.json

Path syntax: JSON Pointer (RFC 6901) uses / as the separator. Array indices are zero-based. The path /domains/0/boundaries/1/mach refers to the mach field of the second boundary in the first domain.

Test operation: The test operation validates a value before applying subsequent operations. If the test fails, the entire patch is rejected.

[
  { "op": "test", "path": "/analysis/dimension", "value": 3 },
  { "op": "replace", "path": "/run_control/iteration", "value": 5000 }
]

This patch updates the iteration count only if analysis.dimension is 3. Use test to guard patches against applying to the wrong case type.

8.4.5 Composition order

The solver applies configuration layers in the following order:

1. Base file (the file passed to the solver)
   ↓
2. $extends chain (resolved recursively from base to leaf)
   ↓
3. --overlay (JSON Merge Patch)
   ↓
4. --patch (JSON Patch)

Each layer merges onto or modifies the result of the previous layer. The final composed configuration is validated before execution begins.

Example:

Linux:

./wake_3d_mixed case.jsonc --overlay mach-08.json --patch cfl-adjust.json

Windows PowerShell:

& "C:\Program Files\Wake CFD\bin\wake_3d_mixed.exe" case.jsonc --overlay mach-08.json --patch cfl-adjust.json
  1. Load case.jsonc
  2. Resolve $extends if present in case.jsonc
  3. Apply mach-08.json via Merge Patch
  4. Apply cfl-adjust.json via JSON Patch
  5. Validate final configuration
  6. Execute

8.5 MPI execution

Linux:

mpirun -n 4 ./wake_3d_mixed case.jsonc
mpiexec -n 4 ./wake_3d_mixed case.jsonc

Windows PowerShell:

mpirun -n 4 wake_3d_mixed.exe case.jsonc
mpiexec -n 4 wake_3d_mixed.exe case.jsonc

In a GPU-aware MPI environment, ranks and GPUs are generally mapped one to one.

Linux:

mpirun -n 4 --bind-to core --map-by ppr:1:numa ./wake_3d_mixed case.jsonc

The solver detects GPU-aware MPI automatically. If detection is incorrect for your stack, force it with WAKE_GPU_AWARE_MPI.

8.5.1 Slurm (Linux HPC clusters)

Slurm is a Linux-based HPC job scheduler. Under Slurm, use srun according to your cluster’s policy.

Linux:

srun ./wake_3d_mixed case.jsonc

Slurm configurations vary by site. Adjust partition, node count, tasks per node, and GPU allocation in the job script. For complete Slurm integration, batch scripts, and working-directory considerations, see Slurm integration.

8.6 Pre-run verification

Verify the following before executing a case to avoid common setup errors. These checks are derived from the Best practices pre-run checklist.

  • Input file syntax: Confirm that the input file uses valid JSONC syntax (// and /* */ comments allowed; JSON5 trailing commas and unquoted keys rejected). Use --validate to check.
  • Dimension match: Confirm that analysis.dimension matches the solver binary (wake_2d_mixed → 2, wake_3d_mixed → 3).
  • Mesh file paths: Confirm that mesh[].file_name paths exist relative to the working directory.
  • Mesh zone and marker names: Confirm that domains[].mesh_zones and boundaries[].mesh_markers match actual names in the mesh file.
  • FR time mode: For analysis.solver=fr, confirm that analysis.time=unsteady. Steady FR is not supported.

For execution errors and resolution procedures, see Troubleshooting.