How peterdsharpe/neuralfoil works
1. Repository purpose and top-level split
- This repo is centered on a standalone Python package, neuralfoil, for fast airfoil aerodynamic prediction.
- The codebase is organized into four major areas: the runtime package, the training pipeline, evaluation/benchmarking/studies, and paper/media assets.
2. Runtime package boundary: neuralfoil/
- neuralfoil is the deployable artifact users import.
- The runtime is intentionally lightweight: NumPy-based inference, with trained network parameters shipped as .npz files in neuralfoil/nn_weights_and_biases/.
- neuralfoil/main.py is the core public API surface; __init__.py exposes package entry points, and _basic_data_type.py defines the internal structured data used to move inputs/outputs through the model.
3. Inference data flow
- User inputs can arrive as airfoil coordinates, .dat files, AeroSandbox airfoil objects, or direct Kulfan/CST parameters.
- Those inputs are normalized into the internal shape representation, then passed through the prediction pipeline.
- The model returns a dictionary-like aerodynamics result with coefficients and related fields such as lift, drag, moment, transition locations, and an analysis_confidence estimate.
4. Geometry representation layer
- A key architectural boundary is the conversion from arbitrary airfoil descriptions into the Kulfan/CST parameterization.
- The repository treats this as the canonical latent geometry space for the neural model: 8 parameters per surface plus leading-edge modification and trailing-edge thickness, for 18 total shape parameters.
- This representation is the bridge between user-facing geometry formats and the neural network’s fixed input space.
5. Model ensemble and size tradeoff
- The package ships multiple pretrained model sizes: xxsmall through xxxlarge.
- These are not separate applications; they are alternative inference backends for the same API, chosen to trade speed against accuracy and smoothness.
- The weights are stored per-size in the package so runtime use does not require PyTorch or training code.
6. Physics-informed hybrid modeling
- The architecture is not “just a neural net”; it blends learned predictions with embedded aerodynamic structure and heuristics.
- The README emphasizes three main sources of domain knowledge: latent-space encoding/decoding, symmetry handling, and dynamic fusion between learned and empirical behavior based on trust/confidence.
- This is a key diagram boundary: the learned MLP is only one part of the overall prediction system.
7. Training subsystem: training/
- The training area is separate from runtime and includes the PyTorch model checkpoints (.pth) and conversion tooling to export them into NumPy-friendly .npz weights.
- training/train.py is the main training entry point, while convert_all_pth_files_to_npz.py bridges training artifacts into the packaged runtime format.
- This establishes a clear offline-to-online pipeline: PyTorch for fitting, NumPy for deployment.
8. Training data generation pipeline
- training/training_data/ contains scripts for generating and merging airfoil datasets, including XFoil-based synthetic data and simpler auxiliary data like cylinders.
- Multiprocessing and batch-generation scripts indicate data production is computationally heavy and designed to run at scale, likely on cluster resources.
- These scripts feed the model-training process and are distinct from the inference package.
9. Sensor-placement / high-dimensional training support
- training/optimal_sensor_placement/ is an auxiliary research subsystem for working with higher-dimensional data and covariances.
- Its files suggest a specialized workflow for choosing informative inputs or measurements, likely tied to the airfoil parameterization and data-efficiency studies.
- This is not part of normal inference, but it supports training and analysis of the learned representation.
10. Evaluation, benchmarking, and reproducibility
- benchmarking/ contains scripts that compare NeuralFoil against XFoil and quantify speed/accuracy tradeoffs.
- The assets in that directory provide fixed reference cases used to produce the published benchmark figures.
- This directory is the evidence layer for the repo: it validates the model, measures speed, and demonstrates confidence scoring.
11. Research studies and exploratory analyses
- studies/ contains one-off experiments and diagnostics: smoothness, extrapolation, control surfaces, post-stall behavior, distribution distance, and speed comparisons.
- These are not runtime dependencies, but they document architectural decisions and limitations through targeted experiments.
- For a diagram, treat them as validation/analysis tooling around the core model rather than part of the serving path.
12. Paper and media assets
- paper/ holds the LaTeX source and generated PDF for the associated publication, plus figure-generation utilities.
- media/ contains logo and illustration scripts used for documentation and repository visuals.
- These support communication and publication, not runtime execution.
13. Testing and automation
- tests/test_neuralfoil.py is the main functional test surface for the package.
- GitHub Actions workflows run pytest and publish on master pushes, so the repo has a standard CI/release boundary around the runtime package.
- setup.py, requirements.txt, and MANIFEST.in define packaging and distribution for installation via pip.
14. External dependency boundary
- The runtime package is deliberately minimal and centered on NumPy.
- The README notes AeroSandbox as the richer integration layer for advanced features like transonics, post-stall, and control-surface deflections; that capability is conceptually adjacent but outside the standalone neuralfoil core.
- XFoil is the main external source of training/benchmark truth, while Supercloud/HPC resources are the offline infrastructure used to generate the large-scale training data and train the models.
15. How to draw the architecture
- A clean diagram would show: user airfoil input formats → geometry normalization/Kulfan encoding → model-size-selected NumPy inference using packaged weights → aerodynamic outputs plus confidence.
- Around that core, show a separate offline path: XFoil/data generation → training scripts in PyTorch → checkpoint conversion → packaged .npz weights.
- Surround both with benchmarking/studies/paper as validation and documentation layers, and CI/release as the distribution boundary.
Main entry points: main.py Main API · nn-small.npz NPZ weights · train.py Train script · run-pytest.yml CI workflows
Components 22
Runtime package
Deployable NumPy inference package imported by users.
- Airfoil inputs · Coordinates, .dat files, AeroSandbox objects, or Kulfan/CST parameters entering the system.
- Main API · Core user-facing prediction entry point.
neuralfoil/main.py - Package entry · Top-level package surface and import wiring.
neuralfoil/__init__.py - Data types · Internal structured data used to move inputs and outputs through the model.
neuralfoil/_basic_data_type.py - Geometry norm · Converts arbitrary airfoil descriptions into the canonical latent geometry space.
- Model sizes · Chooses among shipped xxsmall to xxxlarge pretrained backends.
neuralfoil/nn_weights_and_biases - NPZ weights · Packaged NumPy model parameters used at runtime.
neuralfoil/nn_weights_and_biases/nn-small.npz - Inference core · Lightweight prediction pipeline combining learned and embedded aerodynamic behavior.
- Aero outputs · Returned coefficients, transitions, and analysis confidence.
Training pipeline
Offline PyTorch fitting, data generation, and model export.
- Train script · Main offline training entry point.
training/train.py - Data generation · Synthetic training data production and merging.
training/training_data - XFoil data · External aerodynamic reference used to generate and validate training data.
training/training_data/generate_xfoil_data.py - Sensor study · High-dimensional covariance and sensor-placement support for training and representation studies.
training/optimal_sensor_placement - PTH checkpoints · Saved PyTorch model weights for each model size.
training/nn-small.pth - Export NPZ · Converts trained checkpoints into packaged NumPy weights.
training/convert_all_pth_files_to_npz.py
Evaluation
Benchmarking and research studies around accuracy, speed, and behavior.
- Benchmarks · Speed and accuracy comparisons against XFoil and analysis-confidence cases.
benchmarking - Studies · Exploratory experiments on smoothness, extrapolation, control surfaces, and model behavior.
studies
Paper & media
Publication source and visual assets.
Packaging & CI
Distribution, testing, and automation boundaries.
- Tests · Main package verification surface.
tests/test_neuralfoil.py - CI workflows · Pytest and publish-on-master GitHub Actions workflows.
.github/workflows/run-pytest.yml - Packaging · Package metadata and installation configuration.
setup.py
Connections 23
- Airfoil inputs → Main API: submit · User airfoil descriptions enter the public API.
- Package entry → Main API: expose · Package init re-exports the entry points.
- Main API → Data types: normalize · Inputs are wrapped into internal structured data.
- Main API → Geometry norm: encode · Geometries are converted into the canonical Kulfan latent space.
- Geometry norm → Model sizes: features · Encoded shape parameters feed model-size selection and inference inputs.
- Model sizes → NPZ weights: load · Chosen backend reads shipped NumPy parameters.
- NPZ weights → Inference core: params · Weights and biases parameterize the runtime predictor.
- Data types → Inference core: inputs · Structured runtime data is consumed by inference.
- Inference core → Aero outputs: predict · The model returns aerodynamic coefficients and confidence estimates.
- XFoil data → Data generation: source · XFoil-based truth data feeds dataset generation.
- Data generation → Train script: datasets · Generated and merged data trains the model.
- Sensor study → Train script: support · Sensor-placement and covariance work support training and analysis.
- Train script → PTH checkpoints: fit · Training produces PyTorch checkpoints.
- PTH checkpoints → Export NPZ: convert · Checkpoints are exported into packaged NumPy form.
- Export NPZ → NPZ weights: package · Converted weights are copied into the runtime artifact.
- Benchmarks → Aero outputs: evaluate · Benchmark scripts compare predictions and confidence against references.
- Studies → Inference core: probe · Studies inspect smoothness, extrapolation, and behavior of the inference system.
- Paper → Benchmarks: cite · The paper is supported by benchmark evidence and figures.
- Media → Paper: illustrate · Figures and logos support documentation and publication.
- Tests → Main API: verify · Functional tests exercise the public package surface.
- CI workflows → Tests: run · Automated workflows execute the test suite.
- Packaging → Package entry: build · Packaging defines the distributable runtime artifact.
- CI workflows → Packaging: release · Automation covers publishing and distribution.