NeuralFoil: XFoil-Speed Airfoil Analysis Without the Convergence Failures
NeuralFoil is a practical airfoil aerodynamics analysis tool using physics-informed machine learning, exposed to end-users in pure Python/NumPy.
At a glance
- What is it?
- NeuralFoil replaces XFoil's iterative solver with a trained neural network that returns viscous airfoil polars in about five milliseconds, plus an analysis_confidence value that flags when the prediction is out of distribution. The trade is clear: you get differentiability and guaranteed answers, but you inherit a model's error profile instead of a solver's.
- Who is it for?
- Adopt NeuralFoil if your problem is gradient-based airfoil shape optimization, conceptual design sweeps, or any workflow where XFoil's non-convergence breaks the loop. Do not adopt it if you need a validated viscous solution for certification, if your operating point sits far outside the training envelope, or if you need to inspect boundary layer behavior that the tool does not expose.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 58 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: XFoil Is Accurate and Awkward to Automate
XFoil has been the reference for viscous airfoil analysis for decades, and its accuracy is not in question. Its interface is. It is a Fortran program driven by an interactive menu system, it writes results to files that a calling script has to parse, and it fails to converge at some angle of attack and Reynolds number combinations. That last property is the one that hurts in an optimization loop. A gradient-based optimizer needs a smooth, defined objective value at every point it samples. When the solver returns nothing, the optimizer either crashes or the caller has to invent a penalty, and the invented penalty is not the real physics.
NeuralFoil is aimed at that gap. The README describes it as a hybrid of physics-informed machine learning and analytical models, with a learned core trained on nearly 8 million XFoil runs. The intended user is not someone doing final aerodynamic sign-off. It is an engineer running thousands of candidate shapes through an optimizer, or building a conceptual design trade study where the airfoil polar is one input among many. The project's own framing puts it next to XFoil as a similar tool, not a replacement for it.
What Actually Runs: A NumPy Network With Physics Constraints Baked In
The runtime is pure Python plus NumPy. Training happened in PyTorch, but the shipped artifact executes in NumPy, which is why the dependency list is short and why the package installs without a deep learning stack. The README states the user-facing code is under 500 lines in neuralfoil/main.py, so the surface you interact with is small enough to read in one sitting.
The mechanism is a learned mapping from airfoil geometry and flow conditions to aerodynamic coefficients. The README says physics-based invariants are embedded in the model, and that this is part of why accuracy holds on airfoils outside the training set. The output is a dictionary with keys including analysis_confidence, CL, CD, CM, Top_Xtr, and Bot_Xtr. Top_Xtr and Bot_Xtr are the laminar-to-turbulent transition locations on the upper and lower surfaces, so the model is not just fitting lift and drag curves; it is predicting a transition front.
The property that matters most for optimization is that the outputs are described as C-infinity continuous. XFoil's polars have small discontinuities where the solver switches behavior or struggles to converge, and the README notes NeuralFoil smooths out jagged XFoil predictions. A gradient-based optimizer differentiates through the model, so a discontinuous objective is not a cosmetic problem. This is the design decision that separates NeuralFoil from a solver wrapped in a script.
Eight Model Sizes and the Accuracy Budget You Choose
NeuralFoil ships eight models: xxsmall, xsmall, small, medium, large, xlarge, xxlarge, and xxxlarge. The README presents this as a tradeoff between accuracy and computational cost, and the model_size argument selects one. The default in the examples is xlarge, which is a reasonable signal about where the author thinks the accuracy-cost knee sits.
Having the spectrum available matters more than it first appears. In an outer optimization loop you may evaluate tens of thousands of candidates, and a smaller model that runs faster can be worth more than a larger one that is marginally more accurate, provided the ranking of candidates is preserved. In a final verification pass on a handful of designs, you switch to xxxlarge. The README does not publish a per-model accuracy table in the material available here, so the only way to know whether xxsmall is good enough for your problem is to compare it against xlarge on your own geometry. That comparison is a few lines of code and is the first thing worth doing.
Getting It Running: Three Entry Points and One Dictionary
Installation is a single command:
pip install neuralfoil
The README gives three ways to supply geometry, and they differ in what you already have on hand. If you have a coordinate file, use get_aero_from_dat_file with a filename argument. If you have coordinates in memory, use get_aero_from_coordinates with an n-by-2 NumPy array. If you are already inside AeroSandbox, use get_aero_from_airfoil and pass an asb.Airfoil object. The README notes that any UIUC or NACA airfoil name works with the AeroSandbox path, so asb.Airfoil("naca4412") is valid without any file on disk.
The alpha and Re arguments accept scalars or arrays. The README example passes alpha=np.linspace(-25, 25, 1000) with a single Reynolds number, and states that evaluations are vectorized across alpha and Re. That vectorization is where the speed claim comes from: the README reports roughly 5 milliseconds per analysis, about 30x faster than XFoil for a single case and about 1000x faster for multipoint work. The gap between those two numbers is the vectorization, not a faster solver.
The returned dictionary is the whole interface. You read aero["CL"], aero["CD"], aero["CM"], and aero["analysis_confidence"]. For boundary layer work the README mentions N_crit, forced trips, and outputs including theta, H, u_e/V_infinity, and pressure distributions, but it attributes the extended feature set (transonics, post-stall, control surface deflections) to the AeroSandbox integration rather than the standalone package. If you need those, install aerosandbox as well.
analysis_confidence Is the Feature Worth Building Around
Most surrogate models return a number and leave you to guess whether it means anything. NeuralFoil returns analysis_confidence alongside the coefficients, described in the README as a measure of uncertainty that flags queries where the flow is sensitive or strongly out of distribution.
This changes how you write the optimization. Instead of treating every evaluation as equally trustworthy, you add a constraint on analysis_confidence and let the optimizer find shapes that are both low-drag and inside the region where the model is reliable. The README links to a tutorial notebook in AeroSandbox demonstrating exactly this, and frames the goal as designs that are robust to small changes in shape and flow conditions. That is a real methodological difference from running XFoil and hoping each case converged.
The caveat is that analysis_confidence is itself a model output. It is a learned estimate of trustworthiness, not a guarantee. A high confidence value means the network believes the query resembles its training distribution; it does not mean the prediction matches what a viscous solver would produce. Treat it as a filter for obviously bad queries, not as an error bar you can quote.
Where NeuralFoil Is the Wrong Tool
The README's own accuracy claim is the limitation. NeuralFoil is described as typically accurate to within a few percent of XFoil's predictions, measured on an airfoil developed for a real aircraft program and held out from training. A few percent on drag counts is fine for ranking candidate shapes. It is not fine for a performance guarantee, a contractual specification, or a stability and control analysis where the margin is smaller than the model error. If your deliverable is a number someone signs, run XFoil or a full CFD case.
The second limitation is the training envelope. The model is accurate on out-of-distribution airfoils because of the physics invariants and the diversity of the training set, but out-of-distribution has a boundary somewhere. The README does not define it in the material available here. Unusual geometries, extreme Reynolds numbers, or flow regimes the training data underrepresented will produce low analysis_confidence if you are lucky, and a plausible-looking wrong answer if you are not. There is no fallback solver inside the package.
The third is scope. The standalone package is a 2D airfoil tool. It does not model finite wings, spanwise flow, or three-dimensional effects, and the transonic, post-stall, and control-surface capabilities live in AeroSandbox, not here. If your problem is a wing, NeuralFoil gives you a section polar to feed into a lifting-line or vortex-lattice method. It is not the whole analysis.
XFoil and NeuralFoil Are Not Interchangeable
The obvious alternative is XFoil itself, and the difference is not speed. XFoil solves the boundary layer equations iteratively for each case. It is a numerical solution to a stated physical model, and when it converges you know what you solved. NeuralFoil evaluates a function fitted to 8 million of those solutions. It is interpolation in a high-dimensional space, shaped by physics constraints but still interpolation.
That distinction determines when each is appropriate. XFoil is the right choice when you need one answer you can defend, when the geometry is unusual enough that you are unsure it resembles anything in a training set, or when you need to inspect the boundary layer solution rather than just read its integral quantities. NeuralFoil is the right choice when you need ten thousand answers and the ranking matters more than the absolute value, when the optimizer needs gradients, or when XFoil's convergence failures are the thing blocking your workflow.
A practical pattern is to use both. Run the optimization on NeuralFoil, then re-run the final candidates through XFoil and check that the ordering holds. If it does not, the discrepancy tells you something about your design space. That verification step is cheap because you are only running it on a handful of shapes.
Licence, Maintenance, and What to Check Before You Depend on It
NeuralFoil is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. The trained model weights ship with the package, so the licence covers them as distributed. This is not legal advice; if you are embedding the model in a product, read the LICENSE file and confirm the terms yourself.
Maintenance cost is low by construction. The runtime depends on NumPy, not PyTorch, so there is no heavyweight dependency to keep in step with CUDA versions or framework releases. The repository shows a pytest workflow in GitHub Actions, and the README references an arXiv preprint (2503.16323) and a paper under ./paper/out/main.pdf for the methodology. The user-facing code is under 500 lines, which means an engineer can audit it rather than trust it.
The upgrade risk is the model itself. If a future version retrains on new data, coefficients will shift slightly, and an optimization that converged against one model version may not converge identically against the next. Pin the version in your requirements file if you are reproducing published results. And before you build anything on top, run your own comparison: take the airfoils you actually care about, sweep the alpha and Reynolds number range you actually operate in, and check both the CL and CD agreement against XFoil and the analysis_confidence values that come back. If confidence is low across your operating envelope, the tool is telling you it has not seen your problem before.
Editorial conclusion
Adopt NeuralFoil if your problem is gradient-based airfoil shape optimization, conceptual design sweeps, or any workflow where XFoil's non-convergence breaks the loop. Do not adopt it if you need a validated viscous solution for certification, if your operating point sits far outside the training envelope, or if you need to inspect boundary layer behavior that the tool does not expose. Before committing, verify two things yourself: run your specific airfoil and Reynolds number against XFoil and compare the CL and CD polars, and check the analysis_confidence values your operating points produce. That second check is the one that decides whether the tool is usable for your design space.
Community notes