Add function vsm_settings, aero_geometry_settings and struc_geometry_settings (#99)

- [x] Add function vsm_settings_file
- [x] Add docstrings
- [x] Add example load_extra_settings.jl
- [x] Add fpc_settings.yaml for the example above
- [x] Add script reuse_lint
- [x] Add aero_geometry_file and structure_geometry_file
- [x] Fix JETLS warnings
- [x] Update documentation

Author: ufechner7

REUSE.toml

@@ -4,7 +4,7 @@ version = 1
 path = ["data/settings.yaml", "data/settings_cabauw.yaml", "data/system.yaml", "data/system_cabauw.yaml", 
         "data/settings2.yaml", "data/system2.yaml", "data/Test_flight.arrow", "data/transition.arrow2", 
         "data/failure_low_right.csv", "data/transition.csv", "data/failure_low_right.arrow", 
-        "data/failure_low_right.arrow2", "data/sim_log.arrow", "data/transition.arrow"]
+        "data/failure_low_right.arrow2", "data/sim_log.arrow", "data/transition.arrow", "data/fpc_settings.yaml"]
 SPDX-FileCopyrightText = "2025 Uwe Fechner, Bart van de Lint"
 SPDX-License-Identifier = "CC-BY-4.0"
 

data/fpc_settings.yaml

@@ -0,0 +1,28 @@
+# settings for the 20 qm kite (just as example for an extra settings file)
+fpc_settings:
+    dt:                 0.025  # time step of the flight path controller
+    log_level:          2      # log level, 0=quiet
+    prn:                false
+    prn_ndi_gain:       false
+    prn_est_psi_dot:    false
+    prn_va:             false
+    use_radius:         true
+    use_chi:            true
+    
+    reset_int1:         true   # reset the main integrator to the last estimated turn rate
+    reset_int2:         false  # reset the integrator of the D part at the second time step
+    reset_int1_to_zero: true
+    init_opt_to_zero:   false  # if the root finder should start with zero
+
+    p: 20                      # P gain of the PID controller
+    i: 1.2                     # I gain of the PID controller 
+    d: 10                      # D gain of the PID controller
+    gain: 0.04                 # additional factor for P, I and D
+    c1:  0.0612998898221       # was: 0.0786
+    c2:  1.22597628388         # was: 2.508
+
+    k_c1: 1.6                  # correction factor, used by the NDI block; increase k_c1, if the radius is too small;
+    k_c2: 6.0                  # C2 for the reelout phase was: 7.0
+    k_c2_high: 12.0            # C2 for the reelout phase at high elevation angles was: 14.0
+    k_c2_int:  0.6             # C2 for the intermediate phase LOW_RIGHT, LOW_TURN, LOW_LEFT
+    k_ds: 2.0                  # influence of the depower angle on the steering sensitivity

data/system.yaml

@@ -3,4 +3,7 @@ system:
     wc_settings: "wc_settings.yaml"   # settings of the winch controller
     fpc_settings: "fpc_settings.yaml" # flight path controller settings
     fpp_settings: "fpp_settings.yaml" # flight path planner settings
+    vsm_settings: "vsm_settings.yaml"       # vortex step model settings
+    aero_geometry: "aero_geometry.yaml"     # aerodynamic geometry
+    structural_geometry: "structural_geometry.yaml"   # structural geometry
 

docs/src/developer_notes.md

@@ -70,7 +70,7 @@ They run `jetls check` for `src/` and `examples/` respectively.
 
 ## More effective development with AI tools using Kaimon
 
-It is suggested to install Kaimon if you are using AI tools like Claude or Github Copilot. It allows faster
+It is suggested to install Kaimon if you are using AI tools like Claude or GitHub Copilot. It allows faster
 development and reduces the token usage (energy and costs).
 
 See: https://github.com/kahliburke/Kaimon.jl
@@ -128,6 +128,6 @@ ollama pull qwen3-embedding:0.6b
 
 The Search tab will show a health indicator for both services. If either is not running, the indicator turns red with an error message.
 
-Before you can search, index the project. From the Search tab press m (manage), than a (add) and enter the path
+Before you can search, index the project. From the Search tab press m (manage), then a (add) and enter the path
 for each project you want to index. Then press i (index). To index one project might take 10 minutes, but you have
 to do that only once.

docs/src/functions.md

@@ -15,6 +15,12 @@ copy_examples
 se
 se_dict
 sync_wind!
+wc_settings
+fpc_settings
+fpp_settings
+vsm_settings_file
+aero_geometry_file
+structural_geometry_file
 ```
 Also look at the default example: [settings.yaml](https://github.com/ufechner7/KiteUtils.jl/blob/main/data/settings.yaml) .
 

examples/Project.toml

@@ -3,9 +3,11 @@ ControlPlots = "23c2ee80-7a9e-4350-b264-8e670f12517c"
 KiteUtils = "90980105-b163-44e5-ba9f-8b1c83bb0533"
 KiteViewers = "2e593061-95e7-45e4-95f4-df0491f2e601"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
 REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
 Rotations = "6038ab10-8711-5258-84ad-4b1120ba62dc"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+StructTypes = "856f2bd8-1eba-4b0a-8007-ebc267875bd4"
 
 [sources]
 KiteUtils = {path = ".."}

examples/load_extra_settings.jl

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: 2022 Uwe Fechner
+# SPDX-License-Identifier: MIT
+
+# example of loading extra settings
+using KiteUtils, Parameters, StructTypes
+using KiteUtils.YAML
+
+@with_kw mutable struct FPCSettings @deftype Float64
+    dt::Float64              = 0.02   
+    log_level::Int64         = 2
+    prn::Bool                = false
+    prn_ndi_gain::Bool       = false
+    prn_est_psi_dot::Bool    = false
+    prn_va::Bool             = false
+    use_radius::Bool         = true
+    use_chi::Bool            = true
+    reset_int1::Bool         = true
+    reset_int2::Bool         = false
+    reset_int1_to_zero::Bool = true
+    init_opt_to_zero::Bool   = false
+    p  = 20.0
+    i  = 1.2
+    d  = 10.0
+    gain = 0.04
+    c1 =  0.0612998898221 # was: 0.0786
+    c2 =  1.22597628388   # was: 2.508
+    k_c1 = 1.6
+    k_c2 = 6.0
+    k_c2_high = 12.0
+    k_c2_int  =  0.6
+    k_ds = 2.0
+end
+
+StructTypes.StructType(::Type{FPCSettings}) = StructTypes.Mutable()
+
+if basename(pwd()) == "examples"
+    set_data_path("../data")
+else
+    set_data_path("data")
+end
+
+# update the fields of fcs from a config file with the same field names
+# the config file is expected to be in YAML format
+function update(fcs::FPCSettings)
+    config_file = joinpath(get_data_path(), fpc_settings())
+    if Sys.iswindows()
+        config_file = replace(config_file, "/" => "\\")
+    end
+    if ! isfile(config_file)
+        println("Warning: $config_file not found, using default settings.")
+        return
+    end
+    dict = YAML.load_file(config_file)
+    sec_dict = Dict(Symbol(k) => v for (k, v) in dict["fpc_settings"])
+    StructTypes.constructfrom!(fcs, sec_dict)
+end
+
+fcs = FPCSettings()
+update(fcs)

src/KiteUtils.jl

@@ -50,6 +50,7 @@ export Logger, MyFloat, Settings, SysLog, SysState
 
 import Base.length
 import ReferenceFrameRotations as RFR
+
 export demo_log, demo_state, demo_syslog, export_log, import_log, load_log, save_log # functions for logging
 export euler2rot, length, log!, menu, syslog
 export demo_state_4p, initial_kite_ref_frame                                         # functions for four point kite model
@@ -58,9 +59,11 @@ export acos2, quat2euler, quat2viewer, wrap2pi                           # geome
 export fromEG2W, fromENU2EG, fromEX2EG, fromKS2EX, fromW2SE              # reference frame transformations
 export azn2azw,  calc_clock_angle, calc_course , calc_heading, calc_heading_w # geometric functions
 export calc_orient_rot, enu2ned, is_right_handed_orthonormal, ned2enu
-export wind_vec_from_angles, angles_from_wind_vec
+export angles_from_wind_vec, wind_vec_from_angles
 export copy_settings, get_data_path, load_settings, set_data_path        # functions for reading and copying parameters
-export fpc_settings, fpp_settings, se, se_dict, update_settings, wc_settings
+export aero_geometry_file, fpc_settings, fpp_settings, se, se_dict,
+    structural_geometry_file, update_settings,
+    vsm_settings_file, wc_settings
 export calculate_rotational_inertia
 export AbstractKiteModel
 export init!, next_step!, update_sys_state!

src/settings.jl

@@ -358,6 +358,9 @@ function Base.setproperty!(set::Settings, sym::Symbol, val)
             setfield!(set, sym, Float64(val))
         elseif sym == :wind_vec && !(val isa SVec3) &&
                val isa AbstractVector
+            if length(val) != 3
+                throw(ArgumentError("wind_vec must be an AbstractVector of length 3"))
+            end
             setfield!(set, sym,
                       SVec3(val[1], val[2], val[3]))
         else
@@ -530,24 +533,96 @@ function update_settings(dict, sections, settings=SETTINGS)
     StructTypes.constructfrom!(settings, result)
 end
 
+"""
+    wc_settings(project=PROJECT)
+
+Get the winch controller (WC) settings filename from the project file.
+
+Returns the filename specified in the `wc_settings` field of the system section.
+The project file defaults to the currently active PROJECT.
+"""
 function wc_settings(project=PROJECT)
     # determine which wc_settings to load
     dict = YAML.load_file(joinpath(DATA_PATH[1], project))
     dict["system"]["wc_settings"]
 end
 
+"""
+    fpc_settings(project=PROJECT)
+
+Get the flight path controller (FPC) settings filename from the project file.
+
+Returns the filename specified in the `fpc_settings` field of the system section.
+The project file defaults to the currently active PROJECT.
+"""
 function fpc_settings(project=PROJECT)
     # determine which fpc_settings to load
     dict = YAML.load_file(joinpath(DATA_PATH[1], project))
     dict["system"]["fpc_settings"]
 end
 
+"""
+    fpp_settings(project=PROJECT)
+
+Get the flight path planner (FPP) settings filename from the project file.
+
+Returns the filename specified in the `fpp_settings` field of the system section.
+The project file defaults to the currently active PROJECT.
+"""
 function fpp_settings(project=PROJECT)
-    # determine which fpc_settings to load
+    # determine which fpp_settings to load
     dict = YAML.load_file(joinpath(DATA_PATH[1], project))
     dict["system"]["fpp_settings"]
 end
 
+"""
+    vsm_settings_file(project=PROJECT)
+
+Get the vortex step model (VSM) settings filename from the project file.
+
+Returns the filename specified in the `vsm_settings` field of the system section.
+The project file defaults to the currently active PROJECT.
+"""
+function vsm_settings_file(project=PROJECT)
+    # determine which vsm_settings to load
+    dict = YAML.load_file(joinpath(DATA_PATH[1], project))
+    dict["system"]["vsm_settings"]
+end
+
+"""
+    aero_geometry_file(project=PROJECT)
+
+Get the aerodynamic geometry filename from the project file.
+
+Returns the filename specified in the `aero_geometry` field of the system section.
+The project file defaults to the currently active PROJECT.
+"""
+function aero_geometry_file(project=PROJECT)
+    # determine which aero_geometry to load
+    dict = YAML.load_file(joinpath(DATA_PATH[1], project))
+    dict["system"]["aero_geometry"]
+end
+
+"""
+    structural_geometry_file(project=PROJECT)
+
+Get the structural geometry filename from the project file.
+
+Returns the filename specified in the `structural_geometry` field of the system section.
+Falls back to `struc_geometry` for compatibility.
+The project file defaults to the currently active PROJECT.
+"""
+function structural_geometry_file(project=PROJECT)
+    # determine which structural_geometry to load (or legacy struc_geometry)
+    dict = YAML.load_file(joinpath(DATA_PATH[1], project))
+    sys = dict["system"]
+    if haskey(sys, "structural_geometry")
+        sys["structural_geometry"]
+    else
+        sys["struc_geometry"]
+    end
+end
+
 """
     se(project=PROJECT; relax=false)
 

src/transformations.jl

@@ -155,7 +155,7 @@ function quat2viewer(q::QuatRotation)
     ay = @SVector [1, 0, 0]  # in ENU reference frame this is pointing to the west
     az = @SVector [0, 0, -1] # in ENU reference frame this is pointing down
     rot = rot3d(ax, ay, az, x, y, z) 
-    x, y, z = rot*ax, rot*ay, rot*az # obtain x, y, z in inertial reference frame
+    x, z = rot*ax, rot*az # obtain x, z in inertial reference frame
     pos_kite_ = @SVector ones(3)
     pos_before = pos_kite_ .+ z
     rotation = KiteUtils.rot(pos_kite_, pos_before, -x)
@@ -269,7 +269,7 @@ upwind direction and upwind elevation. All angles in radians.
 - `upwind_elevation`: angle of the upwind direction above the
   east-north plane [rad]
 
-Returns an `MVector{3, Float64}` (east, north, up).
+Returns an `SVec3` (east, north, up).
 """
 function wind_vec_from_angles(v_wind, upwind_dir, upwind_elevation)
     downwind_azimuth = upwind_dir + π