# peterdsharpe/neuralfoil architecture

> Architecture diagram of the GitHub repository peterdsharpe/neuralfoil, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peterdsharpe/neuralfoil
- Repository: https://github.com/peterdsharpe/neuralfoil

## Overview

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: [`neuralfoil/main.py`](https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/main.py) (Main API), [`neuralfoil/nn_weights_and_biases/nn-small.npz`](https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/nn_weights_and_biases/nn-small.npz) (NPZ weights), [`training/train.py`](https://github.com/peterdsharpe/neuralfoil/blob/master/training/train.py) (Train script), [`.github/workflows/run-pytest.yml`](https://github.com/peterdsharpe/neuralfoil/blob/master/.github/workflows/run-pytest.yml) (CI workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime package"]
  node_user_inputs["Airfoil inputs<br/>user data"]
  node_main_api["Main API<br/>public API<br/>[main.py]"]
  node_package_init["Package entry<br/>package export<br/>[__init__.py]"]
  node_basic_data["Data types<br/>runtime types"]
  node_geometry_norm{{"Geometry norm<br/>Kulfan bridge"}}
  node_model_select[("Model sizes<br/>ensemble selector")]
  node_npz_weights[("NPZ weights<br/>inference weights<br/>[nn-small.npz]")]
  node_inference_core["Inference core<br/>NumPy inference"]
  node_outputs["Aero outputs<br/>prediction result"]
end

subgraph group_training["Training pipeline"]
  node_train_entry["Train script<br/>PyTorch training<br/>[train.py]"]
  node_data_gen["Data generation<br/>dataset build"]
  node_xfoil_truth["XFoil data<br/>truth source"]
  node_high_dim["Sensor study<br/>research support"]
  node_pth_checkpoints[("PTH checkpoints<br/>training artifacts<br/>[nn-small.pth]")]
  node_export_npz["Export NPZ<br/>conversion tool"]
end

subgraph group_evaluation["Evaluation"]
  node_benchmarks["Benchmarks<br/>comparison suite"]
  node_studies["Studies<br/>analysis suite"]
end

subgraph group_docs["Paper & media"]
  node_paper["Paper<br/>publication source<br/>[main.tex]"]
  node_media["Media<br/>visual assets"]
end

subgraph group_release["Packaging & CI"]
  node_tests["Tests<br/>[test_neuralfoil.py]"]
  node_ci["CI workflows<br/>automation<br/>[run-pytest.yml]"]
  node_packaging["Packaging<br/>distribution<br/>[setup.py]"]
end

node_user_inputs -->|"submit"| node_main_api
node_package_init -->|"expose"| node_main_api
node_main_api -->|"normalize"| node_basic_data
node_main_api -->|"encode"| node_geometry_norm
node_geometry_norm -->|"features"| node_model_select
node_model_select -->|"load"| node_npz_weights
node_npz_weights -->|"params"| node_inference_core
node_basic_data -->|"inputs"| node_inference_core
node_inference_core -->|"predict"| node_outputs
node_xfoil_truth -->|"source"| node_data_gen
node_data_gen -->|"datasets"| node_train_entry
node_high_dim -.->|"support"| node_train_entry
node_train_entry -->|"fit"| node_pth_checkpoints
node_pth_checkpoints -->|"convert"| node_export_npz
node_export_npz -->|"package"| node_npz_weights
node_benchmarks -.->|"evaluate"| node_outputs
node_studies -.->|"probe"| node_inference_core
node_paper -.->|"cite"| node_benchmarks
node_media -.->|"illustrate"| node_paper
node_tests -->|"verify"| node_main_api
node_ci -->|"run"| node_tests
node_packaging -->|"build"| node_package_init
node_ci -.->|"release"| node_packaging

click node_main_api "https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/main.py"
click node_package_init "https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/__init__.py"
click node_basic_data "https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/_basic_data_type.py"
click node_model_select "https://github.com/peterdsharpe/neuralfoil/tree/master/neuralfoil/nn_weights_and_biases"
click node_npz_weights "https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/nn_weights_and_biases/nn-small.npz"
click node_train_entry "https://github.com/peterdsharpe/neuralfoil/blob/master/training/train.py"
click node_data_gen "https://github.com/peterdsharpe/neuralfoil/tree/master/training/training_data"
click node_xfoil_truth "https://github.com/peterdsharpe/neuralfoil/blob/master/training/training_data/generate_xfoil_data.py"
click node_high_dim "https://github.com/peterdsharpe/neuralfoil/tree/master/training/optimal_sensor_placement"
click node_pth_checkpoints "https://github.com/peterdsharpe/neuralfoil/blob/master/training/nn-small.pth"
click node_export_npz "https://github.com/peterdsharpe/neuralfoil/blob/master/training/convert_all_pth_files_to_npz.py"
click node_benchmarks "https://github.com/peterdsharpe/neuralfoil/tree/master/benchmarking"
click node_studies "https://github.com/peterdsharpe/neuralfoil/tree/master/studies"
click node_paper "https://github.com/peterdsharpe/neuralfoil/blob/master/paper/TeX/main.tex"
click node_media "https://github.com/peterdsharpe/neuralfoil/tree/master/media"
click node_tests "https://github.com/peterdsharpe/neuralfoil/blob/master/tests/test_neuralfoil.py"
click node_ci "https://github.com/peterdsharpe/neuralfoil/blob/master/.github/workflows/run-pytest.yml"
click node_packaging "https://github.com/peterdsharpe/neuralfoil/blob/master/setup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_user_inputs,node_main_api,node_package_init,node_basic_data,node_geometry_norm,node_model_select,node_npz_weights,node_inference_core,node_outputs toneBlue
class node_train_entry,node_data_gen,node_xfoil_truth,node_high_dim,node_pth_checkpoints,node_export_npz toneAmber
class node_benchmarks,node_studies toneMint
class node_paper,node_media toneRose
class node_tests,node_ci,node_packaging toneIndigo
```

## Components

### Runtime package

Deployable NumPy inference package imported by users.

- **Airfoil inputs**: user data · Coordinates, .dat files, AeroSandbox objects, or Kulfan/CST parameters entering the system.
- [Main API](https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/main.py): public API · Core user-facing prediction entry point. · `neuralfoil/main.py`
- [Package entry](https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/__init__.py): package export · Top-level package surface and import wiring. · `neuralfoil/__init__.py`
- [Data types](https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/_basic_data_type.py): runtime types · Internal structured data used to move inputs and outputs through the model. · `neuralfoil/_basic_data_type.py`
- **Geometry norm**: Kulfan bridge · Converts arbitrary airfoil descriptions into the canonical latent geometry space.
- [Model sizes](https://github.com/peterdsharpe/neuralfoil/tree/master/neuralfoil/nn_weights_and_biases): ensemble selector · Chooses among shipped xxsmall to xxxlarge pretrained backends. · `neuralfoil/nn_weights_and_biases`
- [NPZ weights](https://github.com/peterdsharpe/neuralfoil/blob/master/neuralfoil/nn_weights_and_biases/nn-small.npz): inference weights · Packaged NumPy model parameters used at runtime. · `neuralfoil/nn_weights_and_biases/nn-small.npz`
- **Inference core**: NumPy inference · Lightweight prediction pipeline combining learned and embedded aerodynamic behavior.
- **Aero outputs**: prediction result · Returned coefficients, transitions, and analysis confidence.

### Training pipeline

Offline PyTorch fitting, data generation, and model export.

- [Train script](https://github.com/peterdsharpe/neuralfoil/blob/master/training/train.py): PyTorch training · Main offline training entry point. · `training/train.py`
- [Data generation](https://github.com/peterdsharpe/neuralfoil/tree/master/training/training_data): dataset build · Synthetic training data production and merging. · `training/training_data`
- [XFoil data](https://github.com/peterdsharpe/neuralfoil/blob/master/training/training_data/generate_xfoil_data.py): truth source · External aerodynamic reference used to generate and validate training data. · `training/training_data/generate_xfoil_data.py`
- [Sensor study](https://github.com/peterdsharpe/neuralfoil/tree/master/training/optimal_sensor_placement): research support · High-dimensional covariance and sensor-placement support for training and representation studies. · `training/optimal_sensor_placement`
- [PTH checkpoints](https://github.com/peterdsharpe/neuralfoil/blob/master/training/nn-small.pth): training artifacts · Saved PyTorch model weights for each model size. · `training/nn-small.pth`
- [Export NPZ](https://github.com/peterdsharpe/neuralfoil/blob/master/training/convert_all_pth_files_to_npz.py): conversion tool · 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](https://github.com/peterdsharpe/neuralfoil/tree/master/benchmarking): comparison suite · Speed and accuracy comparisons against XFoil and analysis-confidence cases. · `benchmarking`
- [Studies](https://github.com/peterdsharpe/neuralfoil/tree/master/studies): analysis suite · Exploratory experiments on smoothness, extrapolation, control surfaces, and model behavior. · `studies`

### Paper & media

Publication source and visual assets.

- [Paper](https://github.com/peterdsharpe/neuralfoil/blob/master/paper/TeX/main.tex): publication source · LaTeX manuscript and generated paper output. · `paper/TeX/main.tex`
- [Media](https://github.com/peterdsharpe/neuralfoil/tree/master/media): visual assets · Logo and illustration scripts for docs and repository visuals. · `media`

### Packaging & CI

Distribution, testing, and automation boundaries.

- [Tests](https://github.com/peterdsharpe/neuralfoil/blob/master/tests/test_neuralfoil.py): functional tests · Main package verification surface. · `tests/test_neuralfoil.py`
- [CI workflows](https://github.com/peterdsharpe/neuralfoil/blob/master/.github/workflows/run-pytest.yml): automation · Pytest and publish-on-master GitHub Actions workflows. · `.github/workflows/run-pytest.yml`
- [Packaging](https://github.com/peterdsharpe/neuralfoil/blob/master/setup.py): distribution · Package metadata and installation configuration. · `setup.py`

## Connections

- 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.
