by Kyle Bedrich
PropellerToolbox is a high-fidelity Python framework for the design, simulation, and analysis of propellers for UAVs, RC aircraft, and multirotors. By bridging the gap between propeller geometry and complex aerodynamic performance, it enables researchers and engineers to perform rapid trade studies and design optimized propulsion systems.
Powered by NeuralFoil, PropellerToolbox provides full stall and transonic prediction capabilities.
py -m pip install PropellerToolbox- 🔬 Academic Research: Evaluate new propeller geometries with high accuracy for your specific use cases.
✈️ UAV Design: Perform "What-If" trade studies to see how changes in diameter, pitch, chord, and airfoils affect system-level efficiency.- 📐 Custom Geometry: Generate and visualize complex blade geometries with custom twist, sweep, and airfoil sections.
- 🔄 Dynamic Simulation: Model transient responses under varying torque inputs for multirotor control analysis.
This model provides quick, single-threaded performance predictions specifically for APC propellers. While slightly less accurate than APC's proprietary model, it reliably extracts .dat files into dataframes and interpolates data over RPM and velocity. It also integrates maximum RPM limitations and automatically pulls propeller weight, inertia, and cost from the latest manufacturer datasheets.
Intended for high-fidelity simulations, this solver adapts a proven non-linear BEM approach (Available at DigitalCommons@USU).
- Geometry Initialization: Seamlessly initializes using standard APC geometry files or predicts custom blade profiles using simple APC-style labels (e.g., 'E' or 'WE'). Note: Geometry prediction for propellers over 30 inches tends to underpredict chord and should be used with caution.
- Advanced Aerodynamics: Integrates NeuralFoil to predict airfoil coefficients, featuring Prandtl tip loss corrections at positive effective alphas.
- Full Envelope Physics: Computes post-stall, ±180°, and subsonic/transonic/supersonic flow regimes. NeuralFoil predictions are cached to heavily accelerate runtimes.
- Blade Customization: Assigns a unique
asb.Airfoilobject to each blade element, supporting Kulfan parameterization, aerodynamic/geometric twist, and 3D visualization via AeroSandbox. - Adjustable Fidelity: Users can scale the NeuralFoil model size (small to xxxlarge, with medium as default) to trade coefficient prediction speed for accuracy.
This model offers elevated fidelity by capturing complex aerodynamic interactions across the blade.
- Consistent Setup: Imports geometry directly through the BEM model to ensure parity across solvers.
- Flexible Solvers: Choose between a coupled spanwise-induction mode for high-fidelity wake interactions or a local section-by-section mode for rapid comparisons.
- Dynamic Simulation: Supports steady-state performance predictions, dynamic RPM stepping with input torque, and steady-state torque-to-RPM solving.
- Smart Caching: Leverages AeroSandbox and NeuralFoil for section-wise coefficient prediction, utilizing caching for repeated, efficient evaluations.
- Performance Diagnostics: Exposes iteration counts, residuals, and convergence status to help users fine-tune settings.
The figures above shows agreement between UIUC Propeller Database - Volume 4 and PropellerToolbox's higher fidelity BEM and LLT models.
| Model | CT_MAE | CT_RMSE | CT_R2 | CP_MAE | CP_RMSE | CP_R2 |
|---|---|---|---|---|---|---|
| APC | 0.017425 | 0.021999 | 0.694921 | 0.006515 | 0.009733 | 0.591332 |
| BEM | 0.005524 | 0.007270 | 0.966679 | 0.003152 | 0.004007 | 0.930744 |
| LLT | 0.008551 | 0.011132 | 0.921887 | 0.005474 | 0.006877 | 0.795982 |
The table above shows the Root Mean Square Error, Mean Absolute Error and R^2 value of PropellerToolbox's models compared against the UIUC Propeller Database - Volume 4. BEM is shown to provide the highest accuracy. Data and code used for validation can be found in the benchmarks folder.
A competent computer supporting Python 3.11 or greater.
- Python Version: Python 3.11+ (The Microsoft Store version is preferred, as that is what PropellerToolbox is developed with).
- Performance Note: You can multithread the BEM predictions, but this typically only improves runtime if you model more than 60 blade elements.
PropellerToolbox is available on PyPI. You can install it via the command line:
py -m pip install PropellerToolboxYou can also download the source code or clone the repository using GitHub Desktop. To create an editable version of the module (so you don't have to reinstall every time you change the source code), navigate into the root folder and run:
python3 -m pip install -e .(If you don't need an editable version, simply remove the -e argument). Dependencies will install automatically.
Database Notes:
- You may need to delete
APC_Propeller_DB.jsonif you encounter path issues, since it includes local paths to propeller files. This file is included in .gitignore. - To add APC propellers to your local database, initialize an
APC_Databaseobject and run theadd_all_APC()method.
To get an understanding of how PropellerToolbox's models function, explore the tutorials/ folder. It contains Jupyter Notebooks that walk you through interfacing with the module.
All contributions are welcome, whether it is improving documentation, making code neater, or adding new features!
🚨 If you make ANY changes, please create a new branch!
Features I would love to see added include:
- Structural Analysis: Implementing Euler-Bernoulli beam equations using the distributed force along the blades, including preset material properties like foam core composites.
- Vibration Analysis.
- Aeroelasticity: Modeling the effect of propeller deflection and twist under load on performance (especially useful for slow-fly propellers).
- Optimization: Better caching of NeuralFoil predictions for BEM propellers.
- Complex Flow Regimes: Adding the effect of sideslip on propeller performance.
- More Models: Specifically, implementing a Vortex Lattice Method (VLM).
I have spent significant time developing this code. If you use this software for a paper, report, or project, please let me know! I am deeply interested in seeing how this tool is applied.
You can send a copy of your work or a link to kbedrich@tamu.edu.
This software implements methods and uses data described in the following publications:
-
Merrill, R. S., "Nonlinear Aerodynamic Corrections to Blade Element Momentum Model with Validation Experiments," Master's Report, Utah State University, Logan, UT, Dec. 2011. Available at DigitalCommons@USU
-
Dantsker, O.D., Caccamo, M., Deters, R.W., and Selig, M.S., "Performance Testing of APC Electric Fixed-Blade UAV Propellers," AIAA Aviation and Aeronautics Forum and Exposition (Aviation 2022), AIAA Paper 2022-4020, Chicago, IL, June 2022. Available here
This module is based on code primarily used by Texas A&M University Aerospace Design Teams. (SAE Aero Design, Design Build Fly) PropellerToolbox should be used for non-commercial purposes, like academia and research. Please read the Annendum to the License.