Airfoil API Guide
This page groups the public buffalo_wings.airfoil API by role so the runtime, schema, and support types are easier to browse.
Use this package when you want an airfoil creation library that supports multiple analytic NACA families, CST airfoils, spline-backed airfoils, additional analytic shapes, point-defined airfoils, and file-backed airfoil sources.
Use the runtime sections when you want geometry objects and construction helpers.
Use the schema sections when you want serialized configuration types that match the documented airfoil definition forms.
The runtime airfoil classes use a normalized local section frame with the leading edge at (0, 0) and the nominal trailing-edge midpoint at (1, 0).
This means the airfoil chord is 1.0 unless a specific API documents a different convention.
For the source-of-truth schema reference, see Airfoil Geometry Schema.
For the downstream surface-sampling API, see Airfoil Surface Sampling API.
Create Airfoils From Multiple Definition Families
The public airfoil API supports several top-level creation paths so you can start from the kind of definition data you already have.
Analytic NACA families such as
Naca4AirfoilSpec,Naca4ModifiedAirfoilSpec,Naca5AirfoilSpec,Naca5ModifiedAirfoilSpec,Naca16AirfoilSpec,Naca6AirfoilSpec, andNaca6AAirfoilSpec.Additional analytic shapes such as
FlatPlateAirfoilSpec,BiconvexAirfoilSpec,BiconvexParabolaAirfoilSpec,PolygonAirfoilSpec,EllipseAirfoilSpec,CircularArcAirfoilSpec,JoukowskiAirfoilSpec,CstAirfoilSpec, andParsecAirfoilSpec.Spline-backed airfoils with
SplineAirfoilSpecwhen the authoritative stored geometry is Bezier control-point data.Point-defined airfoils with
PointsAirfoilSpecusingsurface_curveorupper_lowerpoint layouts.File-backed airfoils with
FileAirfoilSpec, including structured point payloads and supported text formats.
The currently implemented runtime construction layer supports the analytic NACA families, the normalized EllipseAirfoilSpec path, the CstAirfoilSpec path, and the Bezier-backed SplineAirfoilSpec path.
The broader schema and validation layer already accepts a wider set of airfoil definition families so CLI, GUI, and authoring workflows can validate them consistently.
Typical Workflow
Define an
AirfoilDocumentSpecwhoseairfoilsmapping assigns document-level names to individual airfoil definitions such asNaca4AirfoilSpecorFileAirfoilSpec.Validate the schema with
validate_spec(...)or, for file-backed sources,validate_file_airfoil_source(...).Construct geometry from a valid supported schema with
AirfoilFactory.Work with the resulting
Airfoilobject for sampling, plotting, or downstream wing construction.
Schema Round-Trip For Supported Families
The currently supported schema-backed runtime families support exact schema round-trip.
For naca4, naca4_modified, naca5, naca5_modified, ellipse, cst, and spline, airfoil.spec and airfoil.to_spec() preserve the original supported schema form.
That means designation-based forms stay designation-based, explicit-parameter forms stay explicit-parameter, and AirfoilFactory.from_spec(airfoil.to_spec()) reconstructs the same supported runtime family.
This guarantee currently applies only to the supported runtime construction surface and does not yet extend to planned families such as points or file.
Create Or Load An Airfoil
Base class for airfoil specific geometries. |
|
Construct public airfoil runtime objects from user-facing specs. |
|
Human-readable summary for one airfoil definition spec. |
Use AirfoilFactory.describe_spec(...) when a CLI, UI, or report needs a
stable human-readable description without collapsing everything into one
plain string.
Use AirfoilFactory.default_spec(...),
AirfoilFactory.exact_source_choices(...),
AirfoilFactory.switch_source_exact(...), and
AirfoilFactory.switch_source_approx_result(...) when an editor, CLI, or
reporting workflow needs to inspect or normalize designation-backed and
parameter-backed schema forms without constructing runtime geometry.
import buffalo_wings.airfoil as bwa
spec = bwa.Naca4AirfoilSpec(designation="0012")
summary = bwa.AirfoilFactory.describe_spec(spec)
assert summary.short == "NACA 0012"
assert summary.long == "NACA 4-Digit airfoil defined by designation 0012"
import buffalo_wings.airfoil as bwa
starter = bwa.AirfoilFactory.default_spec("naca16", source="params")
choices = bwa.AirfoilFactory.exact_source_choices("naca16")
converted = bwa.AirfoilFactory.switch_source_exact(
{
"type": "naca16",
"params": {
"ideal_lift_coefficient": 0.3,
"max_thickness": 0.12,
},
},
"designation",
)
assert choices == ("designation", "params")
assert isinstance(starter, bwa.Naca16AirfoilSpec)
assert converted == bwa.Naca16AirfoilSpec(designation="16-312")
Validate Schema And Inspect Diagnostics
Use the validation workflow before construction when you want stable,
queryable diagnostics for malformed schema content, unsupported runtime
families, or file-backed source contents.
This is the recommended entry point for CLI, GUI, and other user-facing
flows that need more than exception-only behavior.
The canonical shared diagnostics API lives in
buffalo_core.diagnostics, even though the airfoil package re-exports
those types for convenience.
For a consolidated explanation of severity, locations, code naming, and
workflow usage, see Diagnostics Guide.
Structured validation result for one airfoil schema definition. |
|
|
Structured diagnostic suitable for programmatic reporting. |
|
Optional context identifying where a diagnostic applies. |
|
Grouped diagnostics emitted by one workflow. |
|
Severity level for a structured diagnostic. |
Validate one schema-backed airfoil definition. |
|
Validate a file-backed airfoil source and its referenced contents. |
Low-Level Runtime Geometry Primitives
These public classes are reusable runtime geometry building blocks.
They are lower-level than the main airfoil entry points and are not meant to be read as an exhaustive list of supported airfoil definition families.
The airfoil-specific primitives in this section also follow the normalized unit-chord convention described above.
The internal Curve base class supports shared curve operations for airfoil internals, but it is not part of the emphasized public construction surface.
Normalized ellipse-based analytic airfoil. |
|
Airfoils that can be decomposed to camber and thickness. |
Prepare Downstream Surface Samples
Use sample_airfoil(...), sample_airfoil_at_xi(...), or sample_airfoil_at_arc_length(...) when a downstream tool needs a stable typed handoff of sampled coordinates, slope, curvature, arc length, and trailing-edge metadata with today’s warning behavior.
Use sample_airfoil_result(...), sample_airfoil_at_xi_result(...), or sample_airfoil_at_arc_length_result(...) when that same workflow should also return a shared buffalo_core.diagnostics.OperationResult[...] wrapper and support explicit sampling warning-policy control.
Use sample_airfoil_boundary(...) when downstream code needs one ordered airfoil boundary distribution with optional arc length, tangent, normal, and curvature fields.
Use surface_samples_to_dict(...), airfoil_surface_samples_to_dict(...), and airfoil_surface_samples_to_json(...) when that downstream handoff should be controlled separately from sampling, and use the inclusion flags when a lighter dict or JSON payload is preferable.
Use write_sampled_airfoil(...), write_sampled_airfoil_at_xi(...), or write_sampled_airfoil_at_arc_length(...) when that workflow should write files in one step, with file_format="json", file_format="selig", or file_format="lednicer".
Use write_airfoil_surface_samples(...) when an existing typed sampling result should be written to a file after inspection or reuse.
In practice, that means the public sampling surface has three tiers:
use the typed
AirfoilSurfaceSamplesdataclasses when downstream Python code wants a validated in-memory object modeluse the
sample_airfoil*_result(...)variants when the sampling workflow should return a shared result wrapper with explicit warning-policy controluse the unified
write_sampled_airfoil* (...)writers when exported file output is the immediate goaluse the two-step
sample_airfoil(...)thenairfoil_surface_samples_to_* (...)orwrite_airfoil_surface_samples(...)workflow when a caller wants to inspect or reuse the typed samples before choosing an export shape
For a lightweight visual inspection workflow built on top of this sampling surface, see the airfoil plotting example in Examples.
Complete downstream sampling payload for both airfoil surfaces. |
|
Sampled airfoil boundary in one ordered point distribution. |
|
Surface-local values paired with an upper-surface membership mask. |
|
Sampled geometry for one airfoil surface in leading-edge order. |
Sample both airfoil surfaces using a standard spacing rule. |
|
Sample both airfoil surfaces with structured diagnostic reporting. |
|
Sample an airfoil as one ordered boundary point distribution. |
|
Sample both surfaces at explicit |
|
Sample both surfaces at explicit |
|
Sample both surfaces at explicit surface-local arc lengths. |
|
Sample both surfaces at explicit arc length with diagnostics. |
|
Sample an airfoil and write the result to a file. |
|
Write a file from explicit |
|
Write a file from explicit arc-length surface samples. |
|
Convert one sampled airfoil surface to plain Python data. |
|
Convert a full two-surface sampling payload to plain Python data. |
|
Convert a full sampled airfoil payload to a JSON string. |
|
Write sampled airfoil surfaces to a file format. |
Export Sampled Airfoils
Use the export helpers when a downstream consumer needs plain Python data, a JSON string, JSON file output, or coordinate-file output rather than typed runtime dataclasses.
The unified file writers are the shortest path when the end product is a file.
The two-step helpers are better when a caller wants to keep the typed samples available for inspection, additional computation, or repeated export with different filters.
Use the inclusion flags to trim optional sections such as native parameters, derivative fields, or diagnostics when a lighter dict or JSON handoff is preferable.
Use the file writers when the end product should be a file, and select file_format="json", file_format="selig", or file_format="lednicer" explicitly.
import buffalo_wings.airfoil as bwa
airfoil = bwa.AirfoilFactory.naca4_from_designation("2412")
samples = bwa.sample_airfoil(
airfoil,
num_points_per_surface=5,
spacing="cosine",
)
payload = bwa.airfoil_surface_samples_to_json(
samples,
include_derivatives=False,
)
This produces a serialized lower-and-upper surface payload while still preserving core geometry metadata such as leading edge, trailing edge, and chord length.
Use write_sampled_airfoil(..., file_format="selig"), file_format="lednicer", or file_format="json" when the required downstream product is a file instead of an in-memory JSON string.
Use The Implemented Analytic NACA Runtime
These classes participate in the currently implemented analytic NACA runtime.
Classic NACA 4-digit airfoil built from a designation. |
|
Parametric NACA 4-digit airfoil built from explicit parameters. |
|
Classic modified NACA 4-digit airfoil built from a designation. |
|
Parametric modified NACA 4-digit airfoil built from explicit params. |
|
Classic NACA 5-digit airfoil built from a designation. |
|
Parametric NACA 5-digit airfoil built from explicit parameters. |
|
Classic modified NACA 5-digit airfoil built from a designation. |
|
Parametric modified NACA 5-digit airfoil built from explicit params. |
Use The Implemented CST Runtime And Exact Conversion Path
These classes and helpers cover the implemented CST runtime surface.
Use CstAirfoil for the canonical airfoil-specific CST path with n1 = 0.5 and n2 = 1.0.
Use CstGeometry for the more general CST class-function path when noncanonical exponents are required.
These two runtimes can represent the same canonical CST shape, but they do not share the same curve parameterization.
CstAirfoil uses the canonical airfoil-specific curve parameterization x = u^2, while CstGeometry keeps the general full-airfoil curve parameterization x = |u|.
That difference means curve-parameter derivatives, breakpoint behavior, and sampled coordinates at the same u value can differ even when the geometric shape is the same.
Use the explicit conversion helpers when you want the exact canonical CST-to-Bezier bridge into the spline family without changing the authoritative CST runtime.
Canonical CST airfoil with fixed airfoil class exponents. |
|
Canonical CST side helper with fixed airfoil class exponents. |
|
General CST airfoil backed by upper and lower CST geometry sides. |
|
One CST side geometry expressed in class-shape form. |
Convert one canonical CST airfoil into an exact Bezier spline airfoil. |
|
Export one canonical CST airfoil as an exact spline schema definition. |
Advanced Internal CST Fitting
Canonical CST fitting is also available as an advanced internal workflow when you need to approximate analytic runtime airfoils or normalized point-backed airfoils with an explicit coefficient-backed CstAirfoil.
The current fitting surface supports runtime-airfoil fitting with value-plus-slope rows, point-backed fitting from supported text or structured point sources, diagnostics-aware OperationResult[...] variants, and adaptive degree search against fit tolerances.
The simplest public-facing starting point is the lightweight CST fitting example in Examples.
For deeper inspection, use the repository tool at tools/airfoil_fitting/inspect_cst_fit.py, which can inspect runtime or point-backed fits, compare error modes, and report adaptive degree-search history.
This capability intentionally lives under buffalo_wings.airfoil.internal.conversion.cst_fit.
That internal location is the supported signal that CST fitting settings such as point weighting, target-metric choice, and adaptive degree search are advanced workflows rather than part of the routine public airfoil API.
Use The Implemented Spline Runtime
These classes cover the currently implemented Bezier-backed spline runtime.
Use SplineAirfoil when the authoritative airfoil geometry is stored as upper and lower Bezier control-point curves rather than as analytic coefficients or source points.
Bezier-backed spline airfoil runtime. |
|
Two-dimensional Bezier curve. |
Define An Airfoil In Schema
These types correspond to top-level user-facing airfoil schema objects.
AirfoilDocumentSpec owns the named airfoils mapping, while the individual airfoil definition specs intentionally do not carry their own schema-level names.
Schema definition for a NACA 4-digit airfoil. |
|
Top-level airfoil schema document. |
|
Schema definition for a modified NACA 4-digit airfoil. |
|
Schema definition for a NACA 5-digit airfoil. |
|
Schema definition for a modified NACA 5-digit airfoil. |
|
Schema definition for a NACA 16-series airfoil. |
|
Schema definition for a NACA 6-series airfoil. |
|
Schema definition for a NACA 6A-series airfoil. |
|
Schema definition for a flat-plate airfoil. |
|
Schema definition for a circular-arc biconvex airfoil. |
|
Schema definition for a parabolic biconvex airfoil. |
|
Schema definition for a polygonal airfoil. |
|
Schema definition for an elliptical airfoil. |
|
Schema definition for a circular-arc airfoil. |
|
Schema definition for a Joukowski airfoil. |
|
Schema dataclass for a file-backed airfoil definition. |
|
Airfoil schema defined directly from inline point coordinates. |
|
Schema definition for a CST airfoil. |
|
Spline-backed airfoil definition. |
|
Schema definition for a PARSEC airfoil. |
Use Nested Schema Building Blocks
These types support nested schema blocks used by the top-level airfoil specs.
Explicit parameter definition for a NACA 4-digit airfoil. |
|
Explicit parameter definition for a modified NACA 4-digit airfoil. |
|
Explicit parameter definition for a NACA 5-digit airfoil. |
|
Explicit parameter definition for a modified NACA 5-digit airfoil. |
|
Explicit parameter definition for a NACA 16-series airfoil. |
|
Thickness inputs for a NACA 6-series airfoil definition. |
|
One additive mean-line component for a NACA 6-series airfoil. |
|
Camber inputs for a NACA 6-series airfoil definition. |
|
Explicit parameter definition for a NACA 6-series airfoil. |
|
Thickness inputs for a NACA 6A-series airfoil definition. |
|
One additive mean-line component for a NACA 6A-series airfoil. |
|
Camber inputs for a NACA 6A-series airfoil definition. |
|
Explicit parameter definition for a NACA 6A-series airfoil. |
|
CST coefficient set for one airfoil surface. |
|
Bezier-backed spline control data for one airfoil surface. |
|
PARSEC leading-edge radius inputs. |
|
PARSEC trailing-edge geometry inputs. |
|
PARSEC surface extremum constraint. |
See Also
For the complete export list, including the ungrouped module view, see Module Reference.