QAirfoilOpt

Quantum-assisted airfoil shape optimization with response-surface QUBO/HOBO models.

QAirfoilOpt combines XFOIL-based aerodynamic sampling, polynomial response surfaces, binary encodings, QUBO/HOBO construction, classical simulated annealing, and optional Kaiwu CIM execution for NACA 4-digit airfoil studies.

The end-to-end workflow diagram is also available as a PDF at docs/workflow.pdf.

Paper: Airfoil shape optimization via coherent Ising machine

Repository contents

• src/qairfoilopt/: reusable Python package.
• scripts/: reproducible experiment and analysis entry points.
• data/results.csv: small benchmark data generated from the XFOIL sweep.
• docs/workflow.png: README teaser workflow diagram.
• docs/workflow.pdf: one-page workflow overview.

Install

python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e .

For development:

pip install -e ".[dev]"
pytest

External tools

XFOIL is required for scripts that run aerodynamic evaluations. Install XFOIL separately and make it reachable by one of:

• setting XFOIL_PATH to the executable path;
• passing --xfoil-path to the scripts that accept it;
• adding xfoil or xfoil.exe to PATH.

Kaiwu SDK is optional and only needed for --enable-cim workflows:

pip install -e ".[quantum]"

If Kaiwu is distributed to you through a vendor-specific wheel or package index, install it according to that vendor's license and instructions. This repository does not redistribute Kaiwu binaries.

Quick start

python scripts/01_xfoil_sweep.py            # benchmark sweep -> data/results.csv
python scripts/02_response_surface_3d.py    # fit 3D RSMs, report R^2
python scripts/03_hobo_1d_pipeline.py       # 1D quartic HOBO + SA
python scripts/04_multi_objective.py        # CL vs CD Pareto front
python scripts/09_baseline_3d_qubo.py --enable-bf   # Table 1 + Fig. 4b

Append --enable-cim to invoke the Kaiwu CIM solver. Reviewer-response analyses (05–08) cover lambda sensitivity, split-Ising density, step-level timing, and the NACA 00xx non-convex case.

Scripts can also be run against the included benchmark data when the workflow does not require fresh XFOIL evaluations.

Reproducibility

The deterministic source-level checks are:

pip install -e ".[dev]"
pytest
python scripts/02_response_surface_3d.py --output data/rsm_fit.json
python scripts/09_baseline_3d_qubo.py --enable-bf --output data/baseline_3d_result.json

The included data/results.csv covers the 7x4x15 NACA grid: 420 attempted samples, 419 valid aerodynamic rows used by the fitting scripts, generated with alpha=5.0, Re=3e6, Mach=0.0, and iters=5000. Re-running scripts/01_xfoil_sweep.py can regenerate the sweep, but exact aerodynamic values and runtimes may differ across XFOIL builds, operating systems, and compiler/runtime libraries.

Classical simulated annealing paths use fixed seeds in the provided scripts. Wall-clock timing fields are expected to vary by machine. CIM workflows are not fully reproducible from this repository alone because they require the external Kaiwu SDK, valid credentials, and vendor infrastructure.

Open-source compliance

The QAirfoilOpt source code is released under the MIT License. Third-party tools are not vendored in this repository; see THIRD_PARTY_NOTICES.md for license notes and installation responsibilities.

When contributing, keep the repository publishable as source code:

• do not commit local credentials, Kaiwu license values, generated checkpoints, machine-specific paths, or third-party binary installers;
• keep optional tools such as XFOIL and Kaiwu documented as external dependencies;
• add or update tests for changes that affect package behavior;
• run pytest before submitting changes.

Report suspected security issues privately to the project maintainers before opening a public issue. Do not include credentials, private paths, proprietary datasets, or vendor license values in public reports.

License

MIT (see LICENSE).