Metadata-Version: 2.4
Name: PropellerToolbox
Version: 0.2.2
Summary: A Python framework for the design, simulation, and optimization of UAV propellers. Features BEMT solver, Neuralfoil 2D airfoil polars for stall modeling, and optimization and trade study capabilities for academia and research.
Home-page: https://github.com/kbedrich/PropellerToolbox/
Author: Kyle Bedrich
Author-email: Kyle Bedrich <kbedrich@tamu.edu>
License: CC BY-NC-SA 4.0
Project-URL: Homepage, https://github.com/kbedrich/PropellerToolbox/
Project-URL: Repository, https://github.com/kbedrich/PropellerToolbox/
Keywords: python,uav,bem,optimization,aerospace,engineering,dbf,propeller,bemt,sae-aero-design,llt
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: arrow>=1.3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=2
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: seaborn>=0.11
Requires-Dist: aerosandbox
Requires-Dist: pyarrow>=20.0.0
Requires-Dist: scikit-learn>=1.6.1
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

![propeller_toolbox_cover_small](media/propeller_toolbox_cover_small.jpg)
# PropellerToolbox

by [Kyle Bedrich](https://www.linkedin.com/in/kylebedrich/)

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.

```bash
py -m pip install PropellerToolbox
```

## 🚀 What is possible with 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.

## 🛠 Model Capabilities & Solvers
 
### APC Propeller Database
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.

### Non-Linear Blade-Element Method (BEM)
Intended for high-fidelity simulations, this solver adapts a proven non-linear BEM approach ([Available at DigitalCommons@USU](https://digitalcommons.usu.edu/cgi/viewcontent.cgi?article=1067&context=gradreports)). 

* **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.Airfoil` object 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.

### Lifting Line Theory (LLT)
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.


# Validation

![Validation UIUC Volume 4, parity plot](media/validation_uiuc_vol_4.png)
![Validation UIUC Volume 4, residual distribution](media/validation_uiuc_vol_4.png)

The figures above shows agreement between [UIUC Propeller Database - Volume 4](https://m-selig.ae.illinois.edu/props/volume-4/propDB-volume-4.html) and PropellerToolbox's higher fidelity BEM and LLT models.

| Model | Rows | CT_MAE   | CT_RMSE  | CT_R2    | CP_MAE   | CP_RMSE  | CP_R2    |
|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|
| APC   | 2659 | 0.017425 | 0.021999 | 0.694921 | 0.006515 | 0.009733 | 0.591332 |
| BEM   | 2659 | 0.005524 | 0.007270 | 0.966679 | 0.003152 | 0.004007 | 0.930744 |
| LLT   | 2659 | 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.

## 💻 Requirements
A competent computer supporting Python 3.11 or greater. 
* **Python Version:** [Python 3.11+](https://apps.microsoft.com/detail/9nrwmjp3717k?hl=en-US&gl=US) (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.

## 🛠️ Installing

PropellerToolbox is available on PyPI. You can install it via the command line:

```bash
py -m pip install PropellerToolbox
```

### Developer Installation
You 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:

```bash
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.json` if 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_Database` object and run the `add_all_APC()` method.

## 📚 Code Examples Folder
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. 

## 🤝 Contributing
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).

### 🎓 Usage in Academia & Research
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**.

### References

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](https://digitalcommons.usu.edu/cgi/viewcontent.cgi?article=1067&context=gradreports)

* 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](https://m-selig.ae.illinois.edu/pubs/DantskerCaccamoDetersSelig-2022-AIAA-Paper-2022-4020-APCEPropTestsVol4.pdf)

 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.
