Skip to main content

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.

Try the OpenAVL app here

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 .avl files
  • 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(), and plot_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 APIs
  • integration — full end-to-end AVLSolver runs on real geometries
  • ui — web GUI session and export helpers
  • reference — numerically validated against Fortran binaries or AVL run-case outputs
  • fixture — validated against stored JSON fixtures
  • smoke — 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–Hallock r/(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 CLmax capping: 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 .avl input. 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/_g sensitivity 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 six VEFF_x derivatives; AVL omits it on some entries.
  • Control/design derivatives from get_stability_derivatives() are per radian; AVL's ST output 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.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openavl 1.1.0
File Size Uploaded Provenance Actions
openavl-1.1.0.tar.gz 227.9 kB Without provenance Details for openavl-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openavl 1.1.0
File Interpreter ABI Platform Actions
openavl-1.1.0-py3-none-any.whl Python 3 none any Details for openavl-1.1.0-py3-none-any.whl

Total release size: 486.8 kB

Release files / openavl-1.1.0.tar.gz

Download URL openavl-1.1.0.tar.gz
Size 227.9 kB
Tags Source
SHA-256 checksum
How to use checksums
a5d0c569e3e3bd24bc54e4c1ec45a0be1697c8fe4fb0953717e1555eb975f072
BLAKE2b-256 checksum
How to use checksums
a324fee837b755deec0d0db00a6b9c571cf59687756bb0433323d18b619fa3b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.4

Release files / openavl-1.1.0-py3-none-any.whl

Download URL openavl-1.1.0-py3-none-any.whl
Size 258.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4b8bb8aa7cd4c7ed87480b789319a89fffdeec0fb6eef95cf1c681f461b5e26d
BLAKE2b-256 checksum
How to use checksums
f70da0e25762d71cfef7ccc6f0c64d3dfcc9a96229c0e50c7105230233a6a3cc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.4

Security for openavl 1.1.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.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page