28 Python SDK

Author and run Wake CFD cases in Python, and automate results and sweeps

pyWakeCFD is an SDK for assembling Wake CFD cases, validating input, and running and observing solvers from Python workflows. It does not connect CUDA or MPI directly to the Python process. Python orchestrates work and manages result files while the solver runs as a separate process.

28.1 When to use it

To create design conditions and compare results in a Jupyter notebook
To automatically vary repeated conditions such as Mach number, angle of attack, and CFL
To connect Wake CFD to internal optimization, post-processing, and data pipelines
To create, validate, and track CLI batch jobs from Python code

While the CLI provides run commands and scheduler jobs, the Python SDK is an automation layer for managing cases and repeated work on top of it.

28.2 Installation

Python 3.10 or later is required. Package name and installation path will be finalized here when public distribution is confirmed.

python -m pip install pywakecfd

# To read history CSV files as pandas DataFrames
python -m pip install "pywakecfd[results]"

In the development repository, install from the SDK directory in editable mode.

cd launcher/python
python -m pip install -e .

28.3 Shortest workflow

Create a case with Case, validate it against the solver, then run it with Run.

from pywakecfd import Case, Mesh, Run

case = (
    Case("naca")
    .mesh(Mesh.from_file("naca.su2"))
    .analysis(dimension=2)
    .fluid("Air")
    .freestream(mach=0.5, aoa_deg=2.0)
    .dbns(convective_scheme="roe", order=2)
    .run_control(max_iter=10_000)
)

case.validate("wake_2d_mixed")
run = Run(case, executable="wake_2d_mixed", workdir="runs/naca").start()
returncode = run.wait()
print(run.status())

The SDK writes runnable JSONC and a manifest to the selected working directory and manages result directories created by the solver.

runs/naca/
├─ case.jsonc
├─ pywakecfd.manifest.json
└─ case_001/
   ├─ wake.status.json
   ├─ history CSV
   ├─ VTK results
   └─ restart files

28.4 Start from an existing JSONC case

Read JSONC exported from the GUI or included in the distribution, then change only the conditions in Python.

from pywakecfd import Case

base = Case.from_jsonc("examples/onera-m6-wing/case.jsonc")
mach_085 = base.set("domains.0.boundaries.1.mach", 0.85)
mach_085.emit("runs/onera-m6-mach-085")

set() returns a changed new Case without modifying the original. This is useful for safely creating comparison cases and retaining their history.

28.5 Parameter sweeps

Sweep creates multiple cases from a baseline Case and paths and values to change.

from pywakecfd import Case, Sweep

base = Case.from_jsonc("examples/onera-m6-wing/case.jsonc")
sweep = Sweep(base, [
    {"numerical_method.dbns.cfl": 5.0},
    {"numerical_method.dbns.cfl": 20.0},
    {"numerical_method.dbns.cfl": 50.0},
])

runs = sweep.run_local(
    executable="wake_3d_mixed",
    root="runs/cfl-sweep",
    max_workers=2,
)

run_local() manages the number of local subprocesses. The SDK does not submit to cluster schedulers such as SLURM, PBS, or MPI, so run generated cases in HPC environments through the CLI and scheduler scripts.

28.6 Results and runtime control

Run.results reads files from the run directory rather than solver memory.

results = run.results
print(results.history_files())
print(results.volume_files())
print(results.restart_files())

When Run starts a gRPC-enabled solver, you can read its state and control CFL, stopping, and restart saving.

with run.runtime(timeout=10) as client:
    for state in client.stream(interval=10):
        print(state.iter, state.res_l2, state.cfl)
        if state.res_l2 < 1e-8:
            client.stop()
            break

Available commands are set_cfl, pause, resume, dump, dump_restart, and stop. Runtime control requires a gRPC-enabled solver build.