Ptera Software

Flapping Wings in Ground Effect

This is Ptera Software: a fast, easy-to-use, and open-source package for analyzing flapping-wing flight.

Quick Start

Install the package with pip (requires Python 3.11, 3.12, or 3.13):

pip install pterasoftware

Then run a simulation. The following snippet defines a simple rectangular wing, solves for its aerodynamics using the steady horseshoe vortex lattice method (VLM), and visualizes the results:

import pterasoftware as ps

airplane = ps.geometry.airplane.Airplane(
    wings=[
        ps.geometry.wing.Wing(
            wing_cross_sections=[
                ps.geometry.wing_cross_section.WingCrossSection(
                    airfoil=ps.geometry.airfoil.Airfoil(
                        name="naca2412",
                    ),
                    num_spanwise_panels=8,
                    control_surface_symmetry_type="asymmetric",
                    spanwise_spacing="cosine",
                ),
                ps.geometry.wing_cross_section.WingCrossSection(
                    airfoil=ps.geometry.airfoil.Airfoil(
                        name="naca2412",
                    ),
                    num_spanwise_panels=None,
                    Lp_Wcsp_Lpp=(0, 5, 0),
                    control_surface_symmetry_type="asymmetric",
                ),
            ],
            symmetric=True,
            symmetryNormal_G=(0, 1, 0),
            symmetryPoint_G_Cg=(0, 0, 0),
        ),
    ],
)

operating_point = ps.operating_point.OperatingPoint()

problem = ps.problems.SteadyProblem(
    airplanes=[airplane], operating_point=operating_point
)

solver = (
    ps.steady_horseshoe_vortex_lattice_method.SteadyHorseshoeVortexLatticeMethodSolver(
        steady_problem=problem
    )
)

solver.run()

ps.output.draw(solver=solver, scalar_type="lift", show_streamlines=True)

Features

  1. Various Aerodynamic Simulation Methods

    • Steady simulations can be run with a standard horseshoe vortex-lattice method (VLM) or a ring VLM.

    • Unsteady simulations use a ring unsteady VLM (UVLM) solver.

    • Unsteady simulations support both fixed and free wakes.

    • Unsteady simulations implement vortex aging to reduce numerical instabilities.

    • All three solvers support surface effects (e.g., ground effect) via the method of images.

  2. Customizable Aircraft Geometry

    • Aircraft can be defined as a collection of one or more wings of any dimensions and positions.

    • Wings can be defined as a collection of two or more wing cross sections of any dimensions and positions.

    • Wing cross sections can be specified to match the mean camber line of an airfoil.

    • The package comes with a massive database of airfoils to choose from, courtesy of the UIUC Airfoil Coordinates Database.

    • Wings are automatically discretized into panels with customizable sizes and spacings.

  3. Customizable Aircraft Motion

    • The relative motion of wings and wing cross sections can be defined using any time-dependent functions of sweep, pitch, and heave angles.

  4. Customizable Operating Points

    • Parameters such as the free-stream velocity, density, angle of attack, angle of sideslip, etc. can be changed by the user.

  5. High-Speed Simulations

    • Using Just-In-Time compilation, Ptera Software can solve many unsteady flapping-wing simulations in less than a minute!

    • Steady simulations take only seconds!

  6. Simulations of Formation Flight

    • Since v2.0.0, Ptera Software has supported simulations with more than one airplane.

    • This feature can be used to analyze the aerodynamics of flapping-wing formation flight!

  7. Save and Load Simulation Results

    • Save solved simulations to JSON files and load them back without re-running.

    • Uses JSON serialization instead of pickle, avoiding arbitrary code execution vulnerabilities.

    • Supports gzip compression for reduced file sizes.

    • Loaded objects are fully compatible with all output and visualization functions.

  8. Features for Flapping-Wing Vehicle Design

    • Ptera Software is focused on developing features to facilitate designing flapping-wing vehicles.

    • For example, use the functions in the trim module to automatically search for a trim operating point for steady and unsteady simulations of aircraft.

  9. Aeroelastic Module for Flapping Flight (Beta)

    • This feature enables co-simulation of structural wing deformation and standard Ptera Software UVLM calculations.

    • Currently the feature offers a simple torsional spring model for each WingCrossSection.

    • Experimental validation and improved deformation models coming soon.

  10. Free Flight Module (Beta)

    • This feature couples Ptera Software’s UVLM with six-degree-of-freedom rigid body dynamics, using the MuJoCo physics engine, so an aircraft flies a free trajectory under its own aerodynamic loads, weight, and inertia.

    • The body’s motion updates the aerodynamics at every time step, capturing the two-way coupling between flight dynamics and unsteady aerodynamics.

    • Currently this feature supports single-airplane free flight.

  11. A Basic GUI

    • This is still in its alpha stage, but we will be adding more functionality soon.

Installation

As a Package

If you haven’t already, install Ptera Software from PyPI (see Quick Start above):

pip install pterasoftware

Your IDE should automatically provide docstring hints for the available classes and functions. For more detailed documentation, visit the Ptera Software documentation site.

From Source

If you want to browse the example scripts or dig into the source code, you will need a local copy of the repository. Follow the environment setup instructions in the Contributing Guidelines to clone the repository, create a virtual environment, and install dependencies.

Once set up, the examples/ directory contains scripts that demonstrate the full range of Ptera Software’s features and solvers. These scripts are also available on the documentation site.

Example Output

This package currently supports five different solvers, a steady horseshoe VLM, a steady ring VLM, an unsteady ring VLM (UVLM), an aeroelastic unsteady ring VLM, and a free flight unsteady ring VLM. Here are examples of the output you can expect to receive from each of them.

Steady Horseshoe VLM

Example Steady Horseshoe VLM Output

Steady Ring VLM

Example Steady Ring VLM Output

Unsteady Ring VLM

Example Unsteady Ring VLM Animation Output

Aeroelastic Unsteady Ring VLM

Example Aeroelastic Unsteady Ring VLM Animation Output

Free Flight Unsteady Ring VLM

Example Free Flight Unsteady Ring VLM Animation Output

Validation

Since the release of version 1.0.0, Ptera Software is now validated against experimental flapping-wing data! See the validation/ directory to run the test case and read a report on the software’s accuracy.

Documentation

For detailed API documentation and guides, visit the Ptera Software documentation site.

How to Contribute

The primary goal of this project is to increase the open-source community’s understanding and appreciation for unsteady aerodynamics in general and flapping-wing flight in particular. This will only happen through your participation. Feel free to request features, report bugs or security issues, and provide suggestions.

Before contributing, make sure to read through the Contributing Guidelines for how to best help out.

Contributors

Supporters

  • Peter Sharpe

  • Suhas Kodali

  • Ramesh Agarwal

  • E. Farrell Helbling

  • Raphael Zufferey

  • Joseph Katz

  • Allen Plotkin

  • Austin Stover

Background

Ptera Software grew out of a desire to make flapping-wing aerodynamics accessible without expensive commercial CFD tools or hard-to-use open-source alternatives. Initially built on AeroSandbox with the support of Peter Sharpe and Suhas Kodali, it has developed into an actively-maintained UVLM package that is well documented, tested, and validated. We hope that with your help, we will increase the open-source community’s interest and understanding of biological flight.