Docu

.github/workflows/CI.yml

@@ -54,3 +54,23 @@ jobs:
       - uses: codecov/codecov-action@v5
         with:
           files: lcov.info
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    steps:
+      - 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 AtmosphericModels
+            DocMeta.setdocmeta!(AtmosphericModels, :DocTestSetup, :(using AtmosphericModels); recursive=true)
+            doctest(AtmosphericModels)'
+

.gitignore

@@ -6,3 +6,5 @@ data/windfield_4050_500_1.0_8.2.npz
 examples/Manifest.toml
 examples/Manifest-v1.10.toml
 examples/Manifest-v1.11.toml
+docs/build
+docs/Manifest.toml

CHANGELOG.md

@@ -4,4 +4,5 @@
 - BREAKING: When constructing an atmospheric model, you MUST pass the parameter set::Settings. This ensures that all parts of the simulation use the same settings struct, and that you can run different simulations with different settings in parallel.
 
 ## Added
-- The function `get_wind(am, x, y, z, t)` which returns a wind vector for the given position and time. It creates a 3D wind field if it does not exist in the data folder. The parameters of this wind field are configured in `settings.yaml`.
+- The function `get_wind(am, x, y, z, t)` which returns a wind vector for the given position and time. It creates a 3D wind field if it does not exist in the data folder. The parameters of this wind field are configured in `settings.yaml`.
+- Documenter generated documentation. 

Project.toml

@@ -16,6 +16,7 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
 ControlPlots = "0.2.7"
+Documenter = "1.13.0"
 FFTW = "1.9.0"
 HypergeometricFunctions = "0.3"
 KiteUtils = "0.6, 0.7, 0.8, 0.9, 0.10"
@@ -30,8 +31,9 @@ julia = "1.10, 1.11"
 [extras]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 ControlPlots = "23c2ee80-7a9e-4350-b264-8e670f12517c"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Remez = "2e7db186-766a-50e7-8928-5c30181fb135"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "BenchmarkTools", "Remez", "ControlPlots"]
+test = ["Test", "BenchmarkTools", "Remez", "ControlPlots", "Documenter"]

data/settings.yaml

@@ -108,7 +108,7 @@ winch:
 
 environment:
     v_wind: 5.324            # wind speed at reference height          [m/s]
-    v_wind_ref: [5.324, 0.0] # wind speed vector at reference height   [m/s]
+    upwind_dir: -90.0        # upwind direction                        [deg]
     temp_ref: 15.0           # temperature at reference height         [°C]
     height_gnd: 0.0          # height of groundstation above see level [m]
     h_ref:  6.0              # reference height for the wind speed     [m]

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+AtmosphericModels = "c59cac55-771d-4f45-b14d-1c681463a295"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,35 @@
+using AtmosphericModels
+using Pkg
+if ("TestEnv" ∈ keys(Pkg.project().dependencies))
+    if ! ("Documenter" ∈ keys(Pkg.project().dependencies))
+        using TestEnv; TestEnv.activate()
+    end
+end
+using Documenter
+
+DocMeta.setdocmeta!(AtmosphericModels, :DocTestSetup, :(using AtmosphericModels); recursive=true)
+
+makedocs(;
+    modules=[AtmosphericModels],
+    authors="Uwe Fechner <[email protected]> and contributors",
+    repo="https://github.com/OpenSourceAWE/KiteUtils.jl/blob/{commit}{path}#{line}",
+    sitename="AtmosphericModels.jl",
+    checkdocs=:none,
+    format=Documenter.HTML(;
+      repolink = "https://github.com/OpenSourceAWE/AtmosphericModels.jl",
+        prettyurls=get(ENV, "CI", "false") == "true",
+        canonical="https://OpenSourceAWE.github.io/AtmosphericModels.jl",
+        assets=String[],
+    ),
+    pages=[
+        "Home" => "index.md",
+        "API"  => "api.md",
+        "Settings" => "settings.md",
+    ],
+)
+
+deploydocs(;
+    repo="github.com/OpenSourceAWE/AtmosphericModels.jl",
+    devbranch="main",
+    push_preview=true,
+)

docs/src/api.md

@@ -0,0 +1,44 @@
+```@meta
+CurrentModule = AtmosphericModels
+```
+
+## Introduction
+Most functions need an instance of the struct `AtmosphericModel` as first parameter,
+which can be created using the following code:
+```julia
+using AtmosphericModels, KiteUtils
+
+set_data_path("data")
+set = load_settings("system.yaml")
+am::AtmosphericModel = AtmosphericModel(set)
+```
+This requires that the files `system.yaml` and `settings.yaml` exist in the folder `data`. See also [Settings](@ref).
+
+## Types
+
+### Exported types
+```@docs
+ProfileLaw
+AtmosphericModel
+AtmosphericModel(set::Settings; nowindfield::Bool=false)
+```
+### Private types
+```@docs
+WindField
+```
+
+## Functions
+
+### Wind shear and air density calculation
+```@docs
+clear
+calc_rho
+calc_wind_factor
+```
+### Wind turbulence calculation
+```@docs
+get_wind
+rel_turbo
+new_windfield
+new_windfields
+```

docs/src/index.md

@@ -0,0 +1,129 @@
+```@meta
+CurrentModule = AtmosphericModels
+```
+# AtmosphericModels
+This package provides functions for modelling the influence of the atmosphere on wind energy systems. It models the air density, the vertical wind profile and the wind turbulence. Further functions to import measured data are planned. 
+
+## Installation
+Install [Julia 1.10](http://www.julialang.org) or later, if you haven't already. You can add AtmosphericModels from  Julia's package manager, by typing 
+```julia
+using Pkg
+pkg"add AtmosphericModels"
+``` 
+at the Julia prompt.
+
+### Running the tests
+Launch Julia using this project and run the tests:
+```julia
+julia --project
+using Pkg
+Pkg.test("AtmosphericModels")
+```
+
+### Running the examples
+If you check out the project using git, you can more easily run the examples:
+```
+git clone https://github.com/OpenSourceAWE/AtmosphericModels.jl
+cd AtmosphericModels.jl
+```
+Launch Julia using this project and run the example menu:
+```julia
+julia --project
+include("examples/menu.jl")
+```
+The first time will take some time, because the graphic libraries will get installed, the second time it is fast.
+
+## Usage
+### Calculate the height dependant wind speed
+```julia
+using AtmosphericModels
+am = AtmosphericModel()
+
+const profile_law = Int(EXPLOG)
+height = 100.0
+wf = calc_wind_factor(am, height, profile_law)
+```
+The result is the factor with which the ground wind speed needs to be multiplied
+to get the wind speed at the given height.
+
+![Wind Profile](wind_profile.png)
+
+The `EXPLOG` profile law is the fitted linear combination of the exponential and the log law.
+
+### Using the turbulent wind field
+You can get a wind vector as function of x,y,z and time using the following code:
+```julia
+using AtmosphericModels, KiteUtils
+
+set_data_path("data")
+set = load_settings("system.yaml")
+am::AtmosphericModel = AtmosphericModel(set)
+
+@info "Ground wind speed: $(am.set.v_wind) m/s"
+
+wf::WindField = WindField(am, am.set.v_wind)
+x, y, z = 20.0, 0.0, 200.0
+t = 0.0
+vx, vy, vz = get_wind(wf, am, x, y, z, t)
+@time get_wind(am, x, y, z, t)
+@info "Wind at x=$(x), y=$(y), z=$(z), t=$(t): v_x=$(vx), v_y=$(vy), v_z=$(vz)"
+@info "Wind speed: $(sqrt(vx^2 + vy^2 + vz^2)) m/s"
+```
+It is suggested to check out the code using git before executing this example,
+because it requires that a data directory with the correct files `system.yaml`
+and `settings.yaml` exists. See below how to do that.
+
+### Plot a wind profile
+```julia
+using AtmosphericModels, KiteUtils, ControlPlots
+am = AtmosphericModel(se())
+
+heights = 6:1000
+wf = [calc_wind_factor(am, height, Int(EXPLOG)) for height in heights]
+
+plot(heights, wf, xlabel="height [m]", ylabel="wind factor")
+```
+
+```julia
+using AtmosphericModels, ControlPlots, KiteUtils
+am = AtmosphericModel(se())
+AtmosphericModels.se().alpha = 0.234  # set the exponent of the power law
+
+heights = 6:200
+wf = [calc_wind_factor(am, height, Int(EXP)) for height in heights]
+
+plot(heights, wf, xlabel="height [m]", ylabel="wind factor")
+```
+
+### Air density
+```julia
+using AtmosphericModels, BenchmarkTools, KiteUtils
+am = AtmosphericModel(se())
+@benchmark calc_rho(am, height) setup=(height=Float64((6.0+rand()*500.0)))
+```
+This gives 4.85 ns as result. Plot the air density:
+```julia
+heights = 6:1000
+rhos = [calc_rho(am, height) for height in heights]
+plot(heights, rhos, legend=false, xlabel="height [m]", ylabel="air density [kg/m³]")
+```
+![Airdensity](airdensity.png)
+
+## Further reading
+These models are described in detail in [Dynamic Model of a Pumping Kite Power System](http://arxiv.org/abs/1406.6218).
+
+## Licence
+This project is licensed under the MIT License. Please see the below WAIVER in association with the license.
+
+## WAIVER
+Technische Universiteit Delft hereby disclaims all copyright interest in the package “AtmosphericModels.jl” (models for airborne wind energy systems) written by the Author(s).
+
+Prof.dr. H.G.C. (Henri) Werij, Dean of Aerospace Engineering
+
+## See also
+- [Research Fechner](https://research.tudelft.nl/en/publications/?search=Uwe+Fechner&pageSize=50&ordering=rating&descending=true)
+- The application [KiteViewer](https://github.com/ufechner7/KiteViewer)
+- the package [KiteUtils](https://github.com/ufechner7/KiteUtils.jl)
+- the packages [KiteModels](https://github.com/ufechner7/KiteModels.jl) and [WinchModels](https://github.com/aenarete/WinchModels.jl) and [KitePodModels](https://github.com/aenarete/KitePodModels.jl)
+- the packages [KiteControllers](https://github.com/aenarete/KiteControllers.jl) and [KiteViewers](https://github.com/aenarete/KiteViewers.jl)
+

docs/src/settings.md

@@ -0,0 +1,44 @@
+```@meta
+CurrentModule = AtmosphericModels
+```
+
+## Settings
+The parameters af the atmospheric model can be configured in the section `environment` of the `settings.yaml` file in the `data` folder.
+
+The file `system.yaml` specifies which `yaml` files are used to configure
+the current project.
+
+### Example for system.yaml
+```yaml
+system:
+    project: "settings.yaml"  # simulator settings
+```
+Often additional `yaml` files, for example for the controller settings are used.
+
+### Example for settings.yaml
+```yaml
+environment:
+    v_wind: 5.324            # wind speed at reference height          [m/s]
+    upwind_dir: -90.0        # upwind direction                        [deg]
+    temp_ref: 15.0           # temperature at reference height         [°C]
+    height_gnd: 0.0          # height of groundstation above see level [m]
+    h_ref:  6.0              # reference height for the wind speed     [m]
+
+    rho_0:  1.225            # air density at zero height and 15 °C    [kg/m³]
+    alpha:  0.234            # exponent of the wind profile law
+    z0:     0.0002           # surface roughness                       [m]
+    profile_law: 1           # 1=EXP, 2=LOG, 3=EXPLOG, 4=FAST_EXP, 5=FAST_LOG, 6=FAST_EXPLOG
+    # the following parameters are for calculating the turbulent wind field using the Mann model
+    use_turbulence: 1.0      # turbulence intensity relative to Cabauw, NL
+    v_wind_gnds: [3.483, 5.324, 8.163] # wind speeds at ref height for calculating the turbulent wind field [m/s]
+    avg_height: 200.0        # average height during reel out          [m]
+    rel_turbs:   [0.342, 0.465, 0.583] # relative turbulence at the v_wind_gnds
+    i_ref: 0.14              # is the expected value of the turbulence intensity at 15 m/s.
+    v_ref: 42.9              # five times the average wind speed in m/s at hub height over the full year    [m/s]
+                             # Cabauw: 8.5863 m/s * 5.0 = 42.9 m/s
+    height_step: 2.0         # use a grid with 2m resolution in z direction                                 [m]
+    grid_step:   2.0         # grid resolution in x and y direction    [m]
+```
+
+## Remarks
+- If the parameter `use_turbulence` is zero, no windfield is loaded.

scripts/build_docu.jl

@@ -0,0 +1,24 @@
+# build and display the html documentation locally
+# you must have installed the package LiveServer in your global environment
+
+using Pkg
+
+function globaldependencies()
+    projectpath = Pkg.project().path
+    basepath, _ = splitdir(projectpath)
+    Pkg.activate()
+    globaldependencies = keys(Pkg.project().dependencies)
+    Pkg.activate(basepath)
+    globaldependencies
+end
+
+if !("LiveServer" in globaldependencies())
+    println("Installing LiveServer globally!")
+    run(`julia -e 'using Pkg; Pkg.add("LiveServer")'`)
+end
+
+if !("Documenter" ∈ keys(Pkg.project().dependencies))
+    using TestEnv
+    TestEnv.activate()
+end
+using LiveServer; servedocs(launch_browser=true)