Skip to content

Fixing major bug in calculation of projected surface area, added stability and so on #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jellepoland merged 4 commits into from
Oct 8, 2025
Merged

Fixing major bug in calculation of projected surface area, added stability and so on #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7a74a72
adding a benchmark
jellepoland Oct 2, 2025
a397bcd
working on stability
jellepoland Oct 7, 2025
3f0d967
corrected major bug in projected area calculation, updated docs, read…
jellepoland Oct 8, 2025
d00521a
Updating changelog pre-release
jellepoland Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 128 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,23 @@
# Vortex Step Method
The Vortex Step Method (VSM) is an enhanced lifting line method that improves upon the classic approach by solving the circulation system at the three-quarter chord position. This adjustment allows for more accurate calculations of lift and drag forces, particularly addressing the shortcomings in induced drag prediction. VSM is further refined by coupling it with 2D viscous airfoil polars, making it well-suited for complex geometries, including low aspect ratio wings, as well as configurations with sweep, dihedral, and anhedral angles. Which are typical for leading-edge inflatable (LEI) kites, that are used in airborne wind energy production, boat-towing and kite-surfing. An open-source example kite is the [TU Delft V3 Kite](https://awegroup.github.io/TUDELFT_V3_KITE/), of which a video is shown below, made using the internal plotting library.
The Vortex Step Method (VSM) is an enhanced lifting line method that improves upon the classic approach by solving the circulation system at the three-quarter chord position. This adjustment allows for more accurate calculations of lift and drag forces, particularly addressing the shortcomings in induced drag prediction. VSM is further refined by coupling it with 2D viscous airfoil polars, making it well-suited for complex geometries, including low aspect ratio wings, as well as configurations with sweep, dihedral, and anhedral angles, typical for leading-edge inflatable (LEI) kites, that are used in airborne wind energy production, boat-towing and kite-surfing. An open-source example kite is the [TU Delft V3 Kite](https://awegroup.github.io/TUDELFT_V3_KITE/), of which a video is shown below, made using the internal plotting library.

![](docs/TUDELFT_V3_KITE_plotly.gif)

The software presented here includes examples for: a rectangular wing and a leading-edge inflatable kite.

A Julia version of this project is available at [VortexStepMethod.jl](https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl)

## Key Features

- **Accurate low-aspect-ratio wing modeling** with enhanced lifting line theory
- **Viscous-inviscid coupling** using 2D airfoil polars (inviscid, CFD, ML-based)
- **Complex geometry support**: sweep, dihedral, anhedral, leading-edge inflatable (LEI) kites
- **Rigid-body stability derivatives**: automatic computation of dCx/dα, dCMy/dq, etc.
- **Trim angle solver**: automatic determination of trimmed angle of attack
- **Non-dimensional rate derivatives**: controls-friendly output (hat_p, hat_q, hat_r)
- **Reference point flexibility**: correctly handles moment reference point for rotational velocities
- **Interactive visualization**: Plotly and Matplotlib geometry and results plotting

## Documentation
For detailed documentation, please refer to the following resources.

Expand All @@ -21,7 +32,9 @@ For detailed documentation, please refer to the following resources.
- [Panel](docs/Panel.md)
- [Solver](docs/Solver.md)
- [Wake](docs/Wake.md)
- [WingGeometry](docs/WingGeometry.md)
- [Wing Geometry](docs/WingGeometry.md)
- [Stability Derivatives](docs/StabilityDerivatives.md)
- [Trim Angle](docs/TrimAngle.md)

**Other**
- [Nomenclature](docs/nomenclature.md)
Expand Down Expand Up @@ -50,7 +63,7 @@ For detailed documentation, please refer to the following resources.
python -m venv venv
```

5. Activate the virtual environment:
4. Activate the virtual environment:

Linux or Mac:
```bash
Expand All @@ -62,7 +75,7 @@ For detailed documentation, please refer to the following resources.
.\venv\Scripts\activate
```

6. Install the required dependencies:
5. Install the required dependencies:

For users:
```bash
Expand All @@ -81,37 +94,130 @@ For detailed documentation, please refer to the following resources.
sudo apt install dvipng
```

7. To deactivate the virtual environment:
6. To deactivate the virtual environment:
```bash
deactivate
```

## Quick Start

Here's a minimal example to get started:

```python
from pathlib import Path
from VSM.core.BodyAerodynamics import BodyAerodynamics
from VSM.core.Solver import Solver

# Load kite geometry from YAML configuration
config_path = "data/TUDELFT_V3_KITE/CAD_derived_geometry/config_kite_CAD_CFD_polars.yaml"
body_aero = BodyAerodynamics.instantiate(
n_panels=30,
file_path=config_path,
spanwise_panel_distribution="uniform"
)

# Set flow conditions
body_aero.va_initialize(
Umag=10.0, # Velocity magnitude [m/s]
angle_of_attack=6.0, # Angle of attack [deg]
side_slip=0.0, # Sideslip angle [deg]
)

# Solve and get results
solver = Solver()
results = solver.solve(body_aero)

print(f"CL = {results['cl']:.3f}")
print(f"CD = {results['cd']:.3f}")
print(f"L/D = {results['cl']/results['cd']:.2f}")
```

For more examples, see the `examples/` directory.

## Dependencies

- numpy
- matplotlib
- scipy
- plotly
- pandas
- neuralfoil
- PyYAML
- scikit-learn
- numba
- screeninfo
- numpy - Numerical computing
- matplotlib - 2D plotting
- scipy - Scientific computing and optimization
- plotly - Interactive 3D visualization
- pandas - Data manipulation
- neuralfoil - Neural network airfoil predictions
- PyYAML - Configuration file parsing
- scikit-learn - Machine learning utilities
- numba - Just-in-time compilation for performance-critical loops
- screeninfo - Display information for plotting

See also [pyproject.toml](pyproject.toml)
See also [pyproject.toml](pyproject.toml) for complete dependency list and version requirements


**Machine Learning**

The code base is adapted to work with a machine learning model trained on more than a hundred thousands Reynolds-average Navier Stokes (RANS) Computational Fluid Dynamics (CFD) simulations made for leading-edge inflatable airfoils, documented in the MSc. thesis of [K.R.G. Masure](https://resolver.tudelft.nl/uuid:865d59fc-ccff-462e-9bac-e81725f1c0c9), the [code base is also open-source accessible](https://github.com/awegroup/Pointwise-Openfoam-toolchain).

As the three trained models, for Reynolds number = 1e6, 5e6 and 1e7 are too large (~2.3GB) for GitHub, they have to be downloaded separately, and added to the `data/ml_models` folder. They are accessible trough [Zenodo](https://doi.org/10.5281/zenodo.16925758), and so is the [CFD data](https://doi.org/10.5281/zenodo.16925833) on which the models are trained. More description on its usages is found in [Airfoil Aerodynamics](docs/AirfoilAerodynamics.md).
As the three trained models, for Reynolds number = 1e6, 5e6 and 1e7 are too large (~2.3GB) for GitHub, they have to be downloaded separately, and added to the `data/ml_models` folder. They are accessible through [Zenodo](https://doi.org/10.5281/zenodo.16925758), and so is the [CFD data](https://doi.org/10.5281/zenodo.16925833) on which the models are trained. More description on its usage is found in [Airfoil Aerodynamics](docs/AirfoilAerodynamics.md).

## Usage Examples

The `examples/` folder contains comprehensive tutorials:

### **Rectangular Wing**
- `rectangular_wing/tutorial.py` - Basic wing analysis workflow

### **TU Delft V3 Kite**
- `tutorial.py` - Complete kite aerodynamic analysis
- `evaluate_stability_derivatives.py` - Stability and control derivatives computation
- `tow_angle_geometry.py` - Geometric tow angle and center of pressure analysis
- `tow_point_location_parametric_study.py` - Design space exploration for tow point
- `kite_stability_dynamics.py` - Natural frequency and oscillation period calculation
- `convergence.py` - Panel count convergence study
- `benchmark.py` - Performance benchmarking

## Usages
Please look at the tutorial on a rectangular wing, where the code usage and settings are fully detailed.
You can find it in `examples/rectangular_wing/tutorial_rectangular_wing.py`
### **Machine Learning for LEI Airfoils**
- `machine_learning_for_lei_airfoils/tutorial.py` - Using ML models for airfoil aerodynamics

See individual files for detailed documentation and usage instructions.

## Performance Optimization

For large-scale parametric studies:

1. **Use fewer panels during exploration** (`n_panels=20-30`), then increase for final results
2. **Numba JIT compilation** automatically accelerates vortex calculations (first run slower)
3. **Parallel studies**: Run multiple configurations using `multiprocessing` or `joblib`
4. **Cache geometries**: Instantiate `BodyAerodynamics` once, reuse with different flow conditions

Example:
```python
# Fast exploration
body_aero = BodyAerodynamics.instantiate(n_panels=20, ...) # ~0.1s per solve

# High accuracy
body_aero = BodyAerodynamics.instantiate(n_panels=100, ...) # ~2s per solve
```

## Troubleshooting

### Common Issues

**Import errors with numba:**
```bash
pip install --upgrade numba
```

**Matplotlib backend issues on Linux:**
```bash
export MPLBACKEND=TkAgg # Or 'Qt5Agg' if PyQt5 installed
```

**Missing ML models:**
Download from [Zenodo](https://doi.org/10.5281/zenodo.16925758) and place in `data/ml_models/`

**Plotly not showing in Jupyter:**
```bash
pip install jupyterlab "ipywidgets>=7.5"
```

Another tutorial is present under `examples/TUDELFT_V3_LEI_KITE/tutorial.py` where a geometry is loaded from .yaml, plotted, distributions are plotted and polars are created to demonstrate the effect of the stall model.
For more issues, check the [GitHub Issues](https://github.com/ocayon/Vortex-Step-Method/issues) page.

## Contributing Guide
Please report issues and create pull requests using the URL:
Expand All @@ -131,7 +237,7 @@ We welcome contributions to this project! Whether you're reporting a bug, sugges
```bash
git checkout -b issue_number-new-feature
```
3. --- Implement your new feature---
3. Implement your new feature
4. Verify nothing broke using **pytest**
```
pytest
Expand Down
133 changes: 133 additions & 0 deletions changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,139 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).


## [2.0.0] - 08-10-2025

### ⚠️ Breaking Changes

#### API Changes in `BodyAerodynamics`

**1. `va.setter` now requires keyword-only arguments:**

The velocity setter has been completely redesigned to properly handle body angular rates and reference points. All arguments after `va` are now **keyword-only**.

**Old usage (v1.1.0):**
```python
# Setting velocity with yaw rate (tuple format)
body_aero.va = (vel_app, yaw_rate)

# Or without yaw rate
body_aero.va = vel_app
```

**New usage (v2.0.0+):**
```python
# Basic velocity setting (no body rates)
body_aero.va = vel_app

# With body rates (keyword arguments required)
body_aero.va = vel_app, roll_rate=p, pitch_rate=q, yaw_rate=r

# With custom reference point for rotational velocity
body_aero.va = vel_app, yaw_rate=r, reference_point=np.array([x, y, z])
```

**Migration guide:**
- Instead of setting it directly using `body_aero.va`, you can instead use `va_initialize()` (see below)

- If you do want to directly set it, you could should write for full control over body rates:
```python
body_aero.va = vel_app, roll_rate=p, pitch_rate=q, yaw_rate=r, reference_point=ref_pt
```

**2. `va_initialize()` signature expanded:**

The initialization method now accepts body angular rates and reference point.

**Old signature (v1.1.0):**
```python
body_aero.va_initialize(Umag, angle_of_attack, side_slip, yaw_rate=0.0)
```

**New signature (v2.0.0+):**
```python
body_aero.va_initialize(
Umag,
angle_of_attack,
side_slip,
pitch_rate=0.0, # NEW
roll_rate=0.0, # NEW
reference_point=None # NEW
)
```

**Migration guide:**
- The `yaw_rate` parameter has been **removed**
- Body rates are now specified via `pitch_rate`, `roll_rate` keywords
- If you need yaw rate, use `pitch_rate` parameter (body-fixed z-axis)
- Most existing code will work without changes if you weren't using `yaw_rate`
- If you were using `yaw_rate`, replace with appropriate body rate:
```python
# Old
body_aero.va_initialize(Umag, alpha, beta, yaw_rate=0.5)

# New (yaw is rotation about body z-axis = pitch_rate)
body_aero.va_initialize(Umag, alpha, beta, pitch_rate=0.5)
```

**3. Rotational velocity calculation changed:**

The method for computing rotational velocity contributions has been fundamentally updated:

- **Old behavior:** Simple uniform yaw rate applied
- **New behavior:** Proper rotational velocity field: `v_rot = omega × (r - r_ref)`
- Accounts for all three body angular rates (roll, pitch, yaw)
- Reference point can be specified (defaults to panel centroids)
- Physically accurate velocity field due to body rotation

**Impact:**
- Results involving body angular rates will differ from v1.1.0
- New results are physically more accurate
- If comparing with v1.1.0 results, expect differences in cases with non-zero angular rates

**4. New property: `_body_rates`**

Body angular rates are now stored and accessible via `_body_rates` property:
```python
p, q, r = body_aero._body_rates # [roll_rate, pitch_rate, yaw_rate]
```

### Added

#### New Modules

**1. `stability_derivatives.py`**
- Compute rigid-body aerodynamic stability derivatives
- Function: `compute_rigid_body_stability_derivatives()`
- Supports derivatives w.r.t. angle of attack (α), sideslip (β), and body rates (p, q, r)
- Optional non-dimensionalization of rate derivatives
- Uses central finite differences for accuracy
- See `docs/StabilityDerivatives.md` for detailed documentation

**2. `trim_angle.py`**
- Find trim angle of attack where pitching moment equals zero
- Function: `compute_trim_angle()`
- Two-phase algorithm: coarse sweep + bisection refinement
- Automatic stability verification
- Configurable convergence tolerances
- See `docs/TrimAngle.md` for detailed documentation

#### New Documentation
- `docs/StabilityDerivatives.md` - Comprehensive guide to stability derivative computation
- `docs/TrimAngle.md` - Guide to trim angle finding with examples
- `docs/README.md` - Updated documentation index with quick-start guide
- Enhanced main `README.md` with Quick Start, Key Features, and Troubleshooting sections

#### New Examples
- `examples/TUDELFT_V3_KITE/tow_angle_geometry.py` - Visualize effect of tow angle on kite geometry
- `examples/TUDELFT_V3_KITE/tow_point_location_parametric_study.py` - Study tow point location effects
- `examples/TUDELFT_V3_KITE/kite_stability_dynamics.py` - Demonstrate stability derivative computation

### Fixed
- Projected area calculation now uses correct trapezoidal integration method
- Reference point handling in rotational velocity calculations


## [1.1.0] - 2025-09-26

### ⚠️ Breaking Changes
Expand Down
Loading
Loading