OpenAVL
A Python port of AVL (Athena Vortex Lattice), Mark Drela's widely-used Fortran aerodynamics solver. OpenAVL matches Fortran AVL 3.52 to about 1e-8, apart from a few AVL bugs it fixes (listed in the user manual). It uses Python and NumPy, making it scriptable, testable, and composable with the broader scientific Python ecosystem.
What It Does
OpenAVL solves the vortex lattice method (VLM) to compute aerodynamic forces and moments on aircraft configurations defined by AVL geometry files (.avl). It supports:
- Lift, drag, and side-force coefficients (CL, CD, CY)
- Pitching, rolling, and yawing moment coefficients (Cm, Cl, Cn)
- Stability derivatives — partial derivatives of forces/moments with respect to angle of attack, sideslip, rotation rates, and control surface deflections
- Trim analysis — Newton-Raphson iteration to satisfy flight constraints (e.g., trim to a target CL)
- Flight dynamics eigenanalysis — identifies phugoid, short-period, Dutch-roll, and spiral modes from a linearized state-space model
- Multi-surface configurations: wings, tails, fins, fuselage bodies, control surfaces
- Geometry API — build aircraft programmatically (
Aircraft,Wing,Section) without.avlfiles - Sectional CLmax capping — approximate stall onset by limiting peak strip lift (Geometry API only)
- Prandtl-Glauert compressibility correction
- CD(CL) viscous drag polars
- 3D geometry preview, spanwise lift distribution, and Cp plots via
AVLSolver.plot_aircraft(),plot_lift_distribution(), andplot_cp()
Installation
pip install openavl
Requirements: Python >= 3.10, NumPy >= 1.24, SciPy >= 1.14, Matplotlib >= 3.7, Numba >= 0.58
Optional extras install with bracket notation. Combine multiple extras as needed (e.g. pip install "openavl[jax,web]").
pip install "openavl[web]" # FastAPI + uvicorn — browser-based GUI
pip install "openavl[jax]" # JAX + jaxlib (CPU) — AD and OpenMDAO integration
pip install "openavl[jax-cuda12]" # JAX with CUDA 12 GPU support
For development, install from source in editable mode:
git clone https://github.com/danielenriquez59/openavl.git
cd openavl
pip install -e ".[dev]" # pytest — run the test suite
Web GUI ([web])
Installs FastAPI, uvicorn, and python-multipart. See Running the Web GUI Locally below.
JAX backend ([jax]) — validation in progress
Enables openavl.jax for reverse-mode automatic differentiation, gradient-based optimization, and OpenMDAO wrappers (see examples/rectangular_wing_opt.py). JAX is not installed with the base package.
pip install "openavl[jax]"
On Windows, if JAX fails to import, install the Microsoft Visual C++ Redistributable (x64) and try pip install "openavl[jax-cuda12]" for CUDA 12 wheels. A standard venv (rather than Anaconda) or WSL can help if native wheels remain problematic.
Enable 64-bit floats before running JAX analysis (required for AVL numerics):
import jax
jax.config.update("jax_enable_x64", True)
Run JAX tests with pytest tests/jax_backend.
The core FlowCondition uses radians for alfa/beta, degrees for
delcon, and body-axis angular velocity divided by freestream speed for
wrot (inverse geometry-length units). JaxAVLComp exposes angles and
controls in radians; OpenAVLGroup exposes them in degrees. Both OpenMDAO
wrappers accept normalized stability-axis rates pb2v, qc2v, and
rb2v, including the angle-dependent conversion to body axes.
JaxAVLSolver.run(), grad(), and jacobian() use the same live-Mach
analysis, including when JIT is enabled. This requires rebuilding and
factoring the influence matrix as Mach changes. Geometry analysis rebuilds
control-normal sensitivities and body influences at the moving lattice
points. Reference area/lengths and the body centerlines remain fixed.
Geometry derivatives assume fixed panel topology and interpolation data;
changes that move a hinge across a panel edge or change panel allocation
are piecewise smooth and should be checked away from those transitions.
Running the Web GUI Locally
OpenAVL ships a browser-based GUI for loading .avl models, editing flight conditions, running the solver, and viewing 3D geometry and results. It wraps the core NumPy solver with a FastAPI backend and is optional — not installed with the base package.
pip install "openavl[web]"
python -m openavl.web
This starts a local server at http://127.0.0.1:8080 and opens it in your default browser. Stop the server with Ctrl+C.
The [web] extra pulls in FastAPI, uvicorn, and python-multipart (for airfoil file uploads). Run web tests with pytest tests/ui.
Documentation
Full user manual — API reference, Geometry API, examples, file formats, and module layout.
Quick Start
from openavl import AVLSolver
# Load an AVL geometry file and set flight conditions
solver = AVLSolver(
"path/to/aircraft.avl",
alpha=2.0, # angle of attack (degrees)
beta=0.0, # sideslip angle (degrees)
vel=64.5, # airspeed (ft/s or m/s, consistent with geometry units)
rho=0.0005846, # air density
gravity=32.18, # gravitational acceleration
cd0=0.00835, # parasitic drag coefficient
xcg=0.02463, # CG x-position (reference frame)
ycg=0.0,
zcg=0.2239,
)
solver.execute_run(max_iter=20)
results = solver.get_results()
print(results["CL"]) # lift coefficient
print(results["CD"]) # drag coefficient
print(results["Cm"]) # pitching moment coefficient
Trimmed Flight
Use constraints to trim the aircraft to a target aerodynamic condition:
from openavl import AVLSolver
solver = AVLSolver("aircraft.avl")
# Set flight condition parameters
solver.set_parameter("velocity", 64.5)
solver.set_parameter("density", 0.0005846)
solver.set_parameter("gravity", 32.18)
solver.set_parameter("mach", 0.1)
# Trim alpha to achieve CL = 0.5, and elevator to achieve Cm = 0
solver.set_constraint("alpha", "cl", 0.5)
solver.set_constraint("elevator", "cm", 0.0)
solver.execute_run(max_iter=20)
results = solver.get_results()
For coordinated level flight with mass data, use setup_trim() to preset longitudinal constraints before adding lateral trim:
solver.set_parameter("cl", 0.7)
solver.setup_trim(mode=1) # level flight or banked turn
solver.set_constraint("elevator", "cm", 0.0)
solver.execute_run()
Stability Derivatives
solver.execute_run()
derivs = solver.get_stability_derivatives()
print(derivs.CL_a) # dCL/d(alpha) — lift curve slope
print(derivs.Cm_a) # dCm/d(alpha) — pitch stiffness
print(derivs.CL_q) # dCL/d(pitch rate)
print(derivs.Cn_r) # dCn/d(yaw rate) — yaw damping
# Control surface derivatives (per radian; keyed by surface name)
print(derivs.CL_d["elevator"])
print(derivs.Cm_d["elevator"])
JAX Automatic Differentiation
Install the optional jax extra to compute derivatives of aerodynamic
coefficients with respect to flight conditions using automatic differentiation:
from openavl.jax import JaxAVLSolver
solver = JaxAVLSolver("aircraft.avl")
flow = solver.run()
gradient = solver.grad("CL")
print(flow.CL)
print(gradient.alfa) # dCL/d(alpha), with alpha in radians
print(gradient.mach) # dCL/d(Mach)
Use solver.jacobian() to differentiate all force and moment coefficients at
once. The JAX backend also supports geometry derivatives and OpenMDAO integration
for gradient-based aircraft optimization. JAX derivatives describe the specified
flight condition; they do not currently include the response of a trim solve.
Eigenvalue / Flight Dynamics Analysis
modes = solver.eigenvalues()
for mode in modes.modes:
print(f"{mode.name}: "
f"freq={mode.frequency_hz:.3f} Hz, "
f"damping={mode.damping_ratio:.3f}")
# Example output:
# Short Period: freq=1.842 Hz, damping=0.712
# Phugoid: freq=0.043 Hz, damping=0.041
# Dutch Roll: freq=0.963 Hz, damping=0.187
# Spiral: time_constant=38.4 s
AVL Geometry Files
OpenAVL reads standard .avl geometry files unchanged from AVL. The format defines:
- Reference quantities (area, chord, span, reference point)
- Surfaces (wings, tails, fins) with sections and airfoil profiles
- Bodies (fuselages)
- Control surfaces with hinge-line definitions
See the AVL documentation for the geometry file format. Example geometries are provided in tests/data/avl/geometries/.
Geometry API
Build aircraft without .avl files and pass the result directly to AVLSolver:
from openavl import AVLSolver, Aircraft
ac = Aircraft(name="Demo", sref=10.0, cref=1.0, bref=8.0)
wing = ac.add_wing("Wing", n_chord=8, n_span=16, symmetric=True)
wing.clmax = 1.2 # optional: cap sectional lift (0 = disabled)
wing.add_section(xyzle=[0, 0, 0], chord=1.0).set_airfoil_naca("2412")
wing.add_section(xyzle=[0.2, 4, 0], chord=0.6)
solver = AVLSolver(ac, base_dir="/path/to/airfoils", alpha=2.0)
solver.execute_run()
See examples/supra_geomapi_example.py for a full programmatic reproduction of the bundled Supra sailplane.
Examples
Five walkthrough scripts in examples/ analyze the Supra 3.4 m F3J sailplane. Run from the repository root after pip install -e .:
| Script | Demonstrates |
|---|---|
supra_example.py |
Load .avl + .mass, trim, stability derivatives, eigenmodes |
supra_geomapi_example.py |
Same analysis via the Geometry API (no .avl file) |
supra_geometry.py |
Shared Supra geometry module imported by other examples |
supra_load_factor.py |
V-n maneuver point: per-surface forces, strip lift distribution |
supra_aero_sweep.py |
Alpha sweep polars (CL, CD, Cm vs angle of attack) |
python examples/supra_example.py
python examples/supra_geomapi_example.py
python examples/supra_load_factor.py
python examples/supra_aero_sweep.py
Visualization
solver.plot_aircraft() # 3D wireframe geometry preview
solver.plot_lift_distribution() # spanwise cl_lstrp after execute_run()
solver.plot_cp() # pressure coefficient on lifting surfaces
Lower-level helpers in openavl.plotting accept .avl paths, Aircraft, or AVLModel objects directly when you do not have a solver instance.
Running Tests
pip install -e ".[dev]"
# Run all tests
pytest
# Run core unit/module tests only
pytest tests/core
# Run end-to-end integration tests
pytest tests/integration
# Run web UI tests (requires optional [web] deps)
pytest tests/ui
# Run JAX tests (requires optional [jax] deps)
pytest tests/jax_backend
# Run by marker (works across all subdirectories)
pytest -m core
pytest -m integration
pytest -m ui
# Run all numerically validated tests (Fortran binaries or AVL run-case refs)
pytest -m reference
Test markers:
core— unit and module tests for solver internals and APIsintegration— full end-to-end AVLSolver runs on real geometriesui— web GUI session and export helpersreference— numerically validated against Fortran binaries or AVL run-case outputsfixture— validated against stored JSON fixturessmoke— quick convergence or structural checks without tight reference tolerances
Project Structure
src/
├── core/ # AVLSolver API, state dataclass, Newton solver, AIC setup
├── aero/ # Force integration, vortex kernels, Trefftz plane, drag polars
├── geom/ # Panel geometry construction, airfoil camber, spacing functions
├── geometry/ # Programmatic Geometry API (Aircraft, Wing, Section, CdclPolar)
├── fileio/ # AVL geometry parser, mass file loader
├── analysis/ # Stability derivatives, trim, eigenvalue analysis
├── plotting/ # 3D geometry preview and spanwise lift distribution plots
└── math/ # LU factorization wrappers, rotation utilities
tests/
├── core/ # Unit and module tests (kernels, geometry, parser, trim, …)
├── integration/ # End-to-end AVLSolver runs on reference geometries
├── ui/ # Web GUI session and export helpers
├── jax_backend/ # JAX differentiable backend (requires pip install -e ".[jax]")
│ ├── core/ # JAX kernels vs NumPy parity (vortex, forces, solve, snapshots)
│ └── integration/ # End-to-end run_analysis, AD validation, OpenMDAO
├── data/avl/ # Reference .avl geometries, mass files, Fortran binaries
└── fixtures/ # JSON golden fixtures from the JS port
Deliberate deviations from AVL
OpenAVL aims for numerical fidelity with AVL 3.50, with a few intentional corrections where the Fortran source is inconsistent or unsafe:
- Leishman R⁴ vortex-core regularization: finite-core vortex velocities
use
r/√(r⁴ + rcore⁴)instead of AVL's Scully/Burnham–Hallockr/(r² + rcore²)model. The Trefftz-plane calculation uses the same R⁴ model for regularized cross-component interactions. This can produce small differences in induced velocity and induced drag when nonzero core radii are active. - Sectional
CLmaxcapping: the Geometry API can optionally cap local strip lift by scaling that strip's near-field forces, moments, and their sensitivities. This is an OpenAVL post-processing extension, disabled by default and unavailable in legacy.avlinput. It does not modify the circulation solution or Trefftz-plane far-field loads. - Trefftz yz-image sensitivities (
IYSYM·IZSYM, ground effect on half-models): AVL adds the yz-image contribution to the far-field velocity but subtracts the matching_u/_d/_gsensitivity terms. OpenAVL uses the same sign for value and sensitivity (verified by FD). Only active when both Y and Z symmetry images are present. - Body-force
1/√(1−M²)sensitivities: OpenAVL applies the Prandtl–Glauert factor consistently to all sixVEFF_xderivatives; AVL omits it on some entries. - Control/design derivatives from
get_stability_derivatives()are per radian; AVL'sSToutput is per degree (multiply by 57.296 to compare). - Degenerate and inactive influence handling: zero-width vortices produce zero influence, inactive Trefftz sources are excluded before singular arithmetic, and cross-component core selection follows component IDs for rectangular as well as square influence evaluations. These guards primarily affect invalid or auxiliary field-point cases and prevent batch shape from changing the selected core radius.
Support the Project
https://buymeacoffee.com/denriquez
Reference Material
Official AVL homepage and documentation:
https://web.mit.edu/drela/Public/web/avl/
License
OpenAVL is licensed under the GNU General Public License v2 (or later).
As a Python port of AVL's vortex-lattice aerodynamics code, OpenAVL is distributed under the same GPL terms: you may copy, modify, and redistribute it provided derivative works remain under the GPL. See the full license text for details.
Metadata
Release files for openavl 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openavl-1.0.0.tar.gz | 227.5 kB | Without provenance | Details for openavl-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openavl-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for openavl-1.0.0-py3-none-any.whl |
Total release size: 486.1 kB
Security for openavl 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.