diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index cbee4ea7..38e3faf8 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -62,4 +62,26 @@ jobs: with: files: lcov.info token: ${{ secrets.CODECOV_TOKEN }} - \ No newline at end of file + docs: + name: Documentation + runs-on: ubuntu-latest + timeout-minutes: 40 + steps: + - name: Install matplotlib + run: if [ "$RUNNER_OS" = "Linux" ]; then sudo apt-get install -y python3-matplotlib; fi + shell: bash + - uses: actions/checkout@v4 + - uses: julia-actions/setup-julia@v2 + - uses: julia-actions/cache@v2 + - uses: julia-actions/julia-buildpkg@v1 + - uses: julia-actions/julia-docdeploy@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} + - run: | + julia --project=docs -e ' + using Documenter: DocMeta, doctest + using VortexStepMethod + DocMeta.setdocmeta!(VortexStepMethod, :DocTestSetup, :(using VortexStepMethod); recursive=true) + doctest(VortexStepMethod)' + \ No newline at end of file diff --git a/.gitignore b/.gitignore index 63455d90..7fc38c41 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ Manifest.toml .vscode/settings.json venv results/TUDELFT_V3_LEI_KITE/polars/tutorial_testing_stall_model_n_panels_54_distribution_split_provided.pdf +docs/build/ diff --git a/Project.toml b/Project.toml index d13e9bb8..88424f9b 100644 --- a/Project.toml +++ b/Project.toml @@ -16,7 +16,6 @@ Measures = "442fdcdd-2543-5da2-b0f3-8c86c306513e" NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec" StaticArrays = "90137ffa-7385-5640-81b9-e52037218182" Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2" -Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" [compat] BenchmarkTools = "1" @@ -29,3 +28,10 @@ Measures = "0.3" NonlinearSolve = "4" StaticArrays = "1" Statistics = "1" + +[extras] +Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" + +[targets] +test = ["Test", "Documenter"] diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 00000000..ff4a6726 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,3 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +VortexStepMethod = "ed3cd733-9f0f-46a9-93e0-89b8d4998dd9" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..13539d7f --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,27 @@ +using VortexStepMethod +using Pkg +if ("TestEnv" ∈ keys(Pkg.project().dependencies)) + if ! ("Documents" ∈ keys(Pkg.project().dependencies)) + using TestEnv; TestEnv.activate() + end +end +using Documenter + +DocMeta.setdocmeta!(VortexStepMethod, :DocTestSetup, :(using VortexStepMethod); recursive=true) + +makedocs(; + modules=[VortexStepMethod], + authors="Uwe Fechner , Bart van de Lint and contributors", + sitename="VortexStepMethod.jl", + checkdocs=:none, + format = Documenter.HTML(prettyurls = haskey(ENV, "CI")), + pages=[ + "Home" => "index.md", + "Exported Functions" => "functions.md", + ], +) + +deploydocs(; + repo="github.com/Albatross-Kite-Transport/VortexStepMethod.jl", + devbranch="main", +) diff --git a/docs/src/functions.md b/docs/src/functions.md new file mode 100644 index 00000000..6860a38b --- /dev/null +++ b/docs/src/functions.md @@ -0,0 +1,20 @@ +```@meta +CurrentModule = VortexStepMethod +``` +## Main Plotting Functions +```@docs +plot_geometry +plot_distribution +plot_polars +``` + +## Helper Functions +```@docs +set_plot_style +save_plot +show_plot +plot_line_segment! +set_axes_equal! +create_geometry_plot +generate_polar_data +``` \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..6500fa16 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,136 @@ +```@meta +CurrentModule = VortexStepMethod +``` + +# Simulation of a 3D airfoil using the 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, among the most important details. 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. + +The software presented here includes a couple of examples: a rectangular wing, a leading-edge inflatable kite and a ram-air kite. + +This package was translated from the Python code version 1.0.0 available at https://github.com/ocayon/Vortex-Step-Method with some extensions as documented in [News.md](https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl/blob/main/NEWS.md). + +## Installation +Install [Julia 1.10](https://ufechner7.github.io/2024/08/09/installing-julia-with-juliaup.html) or later, +if you haven't already. On Linux, make sure that Python3, Matplotlib and LaTeX are installed: +``` +sudo apt install python3-matplotlib +sudo apt install texlive-full texlive-fonts-extra cm-super +``` + +Before installing this software it is suggested to create a new project, for example like this: +```bash +mkdir test +cd test +julia --project=. +``` +Then add VortexStepMethod from Julia's package manager, by typing: +```julia +using Pkg +pkg"add https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl" +``` +at the Julia prompt. You can run the unit tests with the command: +```julia +pkg"test VortexStepMethod" +``` + +## Running the examples +If you have git installed, check out this repo because it makes it easier to understand the code: +```bash +mkdir repos +cd repos +git clone https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl +cd VortexStepMethod.jl +``` +You can launch Julia with: +```bash +julia --project +``` +or with: +```bash +./bin/run_julia +``` +In Julia, first update the packages: +```julia +using Pkg +Pkg.update() +``` +and then you can execute the first example: +```julia +include("examples/rectangular_wing.jl") +``` +To browse the code, it is suggested to use [VSCode](https://code.visualstudio.com/) with the Julia plugin. + +## Input +Three kinds of input data is needed: + +- The wing geometry, defined by section: + - rec wing two section, two point + polars + - kite: model of polars included, n sections to define + +- The airflow: + - v_app vector + +- The configuration: + - how many panels + --> two sections make a panel. + +Apart from the wing geometry there is no input file yet, the input has to be defined in the code. + +### Example for defining the required input: +```julia + +# Step 1: Define wing parameters +n_panels = 20 # Number of panels +span = 20.0 # Wing span [m] +chord = 1.0 # Chord length [m] +v_a = 20.0 # Magnitude of inflow velocity [m/s] +density = 1.225 # Air density [kg/m³] +alpha_deg = 30.0 # Angle of attack [degrees] +alpha = deg2rad(alpha_deg) + +# Step 2: Create wing geometry with linear panel distribution +wing = Wing(n_panels, spanwise_panel_distribution="linear") + +# Add wing sections - defining only tip sections with inviscid airfoil model +add_section!(wing, + [0.0, span/2, 0.0], # Left tip LE + [chord, span/2, 0.0], # Left tip TE + "inviscid") +add_section!(wing, + [0.0, -span/2, 0.0], # Right tip LE + [chord, -span/2, 0.0], # Right tip TE + "inviscid") + +# Step 3: Initialize aerodynamics +wa = WingAerodynamics([wing]) + +# Set inflow conditions +vel_app = [cos(alpha), 0.0, sin(alpha)] .* v_a +set_va!(wa, (vel_app, 0.0)) # Second parameter is yaw rate +``` +It is possible to import the wing geometry using an `.obj` file as shown in the example `ram_air_kite.jl`. + +Surfplan files can be converted to an input for `VortexStepMethod.jl` using the [SurfplanAdapter](https://github.com/jellepoland/SurfplanAdapter). + +## Output +- CL, CD, CS (side force coefficient) +- the spanwise distribution of forces + --> moment coefficients (will be implemented in release 1.1) + +## Citation +If you use this project in your research, please consider citing it. +Citation details can be found in the [CITATION.cff](https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl/blob/main/CITATION.cff) file included in this repository. + +## License +This project is licensed under the MIT License - see the [LICENSE](https://github.com/Albatross-Kite-Transport/VortexStepMethod.jl/blob/main/LICENSE) file for details. + +### Copyright +Copyright (c) 2022 Oriol Cayon + +Copyright (c) 2024 Oriol Cayon, Jelle Poland, TU Delft + +Copyright (c) 2025 Oriol Cayon, Jelle Poland, Bart van de Lint + diff --git a/src/plotting.jl b/src/plotting.jl index 44490db4..36e77e9c 100644 --- a/src/plotting.jl +++ b/src/plotting.jl @@ -5,7 +5,7 @@ Set the default style for plots using LaTeX. # Arguments: -- `titel_size: size of the plot title in points (default: 16) +- `titel_size`: size of the plot title in points (default: 16) """ function set_plot_style(titel_size=16) rcParams = plt.PyDict(plt.matplotlib."rcParams") @@ -112,12 +112,15 @@ function plot_line_segment!(ax, segment, color, label; width=3) end """ - set_axes_equal!(ax) + set_axes_equal!(ax; zoom=1.8) Set 3D plot axes to equal scale. # Arguments - ax: 3D plot axis + +# Keyword arguments +zoom: zoom factor (default: 1.8) """ function set_axes_equal!(ax; zoom=1.8) x_lims = ax.get_xlim3d() ./ zoom @@ -153,7 +156,8 @@ Create a 3D plot of wing geometry including panels and filaments. # Keyword arguments - zoom: zoom factor (default: 1.8) """ -function create_geometry_plot(wing_aero::WingAerodynamics, title, view_elevation, view_azimuth; zoom=1.8) +function create_geometry_plot(wing_aero::WingAerodynamics, title, view_elevation, view_azimuth; + zoom=1.8) set_plot_style(28) panels = wing_aero.panels @@ -245,16 +249,16 @@ end Plot wing geometry from different viewpoints and optionally save/show plots. # Arguments: -- wing_aero: struct of type WingAerodynamics +- `wing_aero`: struct of type WingAerodynamics - title: plot title # Keyword arguments: -- data_type: string with the file type postfix (default: ".pdf") -- save_path: path for saving the graphic (default: `nothing``)- is_save -- is_save: boolean value, indicates if the graphic shall be saved (default: `false`) -- is_show: boolean value, indicates if the graphic shall be displayed (default: `false`) -- view_elevation: initial view elevation angle (default: 15) [°] -- view_azimuth: initial view azimuth angle (default: -120) [°] +- `data_type``: string with the file type postfix (default: ".pdf") +- `save_path`: path for saving the graphic (default: `nothing`) +- `is_save`: boolean value, indicates if the graphic shall be saved (default: `false`) +- `is_show`: boolean value, indicates if the graphic shall be displayed (default: `false`) +- `view_elevation`: initial view elevation angle (default: 15) [°] +- `view_azimuth`: initial view azimuth angle (default: -120) [°] """ function plot_geometry(wing_aero::WingAerodynamics, title; @@ -565,10 +569,10 @@ end """ plot_polars(solver_list, wing_aero_list, label_list; - literature_path_list=String[], angle_range=range(0, 20, 2), angle_type="angle_of_attack", angle_of_attack=0.0, - side_slip=0.0, v_a=10.0, title="polar", data_type=".pdf", save_path=nothing, - is_save=true, - is_show=true) + literature_path_list=String[], angle_range=range(0, 20, 2), angle_type="angle_of_attack", + angle_of_attack=0.0, side_slip=0.0, v_a=10.0, + title="polar", data_type=".pdf", save_path=nothing, + is_save=true, is_show=true) Plot polar data comparing different solvers and configurations.