Merge pull request #214 from ufechner7/transform

- Adds a Transform struct, which is used in the SystemStructure to describe the orientation of the structure.
- Adds images to the documentation, which were removed when @example was removed.
- Improves the docs and docstrings

Author: 1-Bart-1

.gitignore

@@ -1,3 +1,4 @@
+LocalPreferences.toml
 *.arrow
 *.bin
 *.xopp

AUTHORS.md

@@ -7,7 +7,7 @@ SPDX-License-Identifier: MIT
 This project was started by Uwe Fechner in 2022 with the goal to make the results 
 of his PhD thesis on the simulation and control of kite power systems, re-coded in a fast and modern programming language, available to the public.
 
-Bart van de Lint joined the project in 2024. His major contribution is the first modelling toolkit (MTK) based model, a ram-air kite model.
+Bart van de Lint joined the project in 2024. His major contribution is the first ModelingToolkit (MTK) based model, a ram-air kite model.
 
 ## Developers
 - Uwe Fechner, Delft/ Den Haag, The Netherlands -  original author of the `KPS3` and `KPS4` kite models

Manifest-v1.10.toml.default

@@ -2,7 +2,7 @@
 
 julia_version = "1.10.9"
 manifest_format = "2.0"
-project_hash = "e5116e83aee3763e3ebd89b0de5522b585f68fec"
+project_hash = "098d81951e8c706049a0f77aa39c5c7b3d03fe19"
 
 [[deps.ADTypes]]
 git-tree-sha1 = "e2478490447631aedba0823d4d7a80b2cc8cdb32"
@@ -611,9 +611,9 @@ uuid = "4e289a0a-7415-4d19-859d-a7e5c4648b56"
 version = "1.0.5"
 
 [[deps.EnzymeCore]]
-git-tree-sha1 = "7d7822a643c33bbff4eab9c87ca8459d7c688db0"
+git-tree-sha1 = "8272a687bca7b5c601c0c24fc0c71bff10aafdfd"
 uuid = "f151be2c-9106-41f4-ab19-57ee4f262869"
-version = "0.8.11"
+version = "0.8.12"
 weakdeps = ["Adapt"]
 
     [deps.EnzymeCore.extensions]
@@ -786,9 +786,9 @@ uuid = "d25df0c9-e2be-5dd7-82c8-3ad0b3e990b9"
 version = "0.1.5"
 
 [[deps.InlineStrings]]
-git-tree-sha1 = "6a9fde685a7ac1eb3495f8e812c5a7c3711c2d5e"
+git-tree-sha1 = "8594fac023c5ce1ef78260f24d1ad18b4327b420"
 uuid = "842dd82b-1e85-43dc-bf29-5d0ee9dffc48"
-version = "1.4.3"
+version = "1.4.4"
 weakdeps = ["ArrowTypes", "Parsers"]
 
     [deps.InlineStrings.extensions]
@@ -889,9 +889,9 @@ version = "0.3.8"
 
 [[deps.KiteUtils]]
 deps = ["Arrow", "CSV", "DocStringExtensions", "LinearAlgebra", "OrderedCollections", "Parameters", "Parsers", "Pkg", "PrecompileTools", "RecursiveArrayTools", "ReferenceFrameRotations", "Rotations", "StaticArrays", "StructArrays", "StructTypes", "YAML"]
-git-tree-sha1 = "ef1ab34bdb8c1bcf06f99b4364cae5df1be6936a"
+git-tree-sha1 = "93659cbb96514bafd053ae0e81d08d15248040e9"
 uuid = "90980105-b163-44e5-ba9f-8b1c83bb0533"
-version = "0.10.10"
+version = "0.10.11"
 
 [[deps.Krylov]]
 deps = ["LinearAlgebra", "Printf", "SparseArrays"]

data/model_1.10_ram_dynamic_3_seg.bin.default.xz

@@ -18,6 +18,8 @@ Segment
 Tether
 Winch
 Group
+Wing
+Transform
 SystemStructure
 ```
 

data/model_1.11_ram_dynamic_3_seg.bin.default.xz

@@ -20,13 +20,16 @@ set = se("system_ram.yaml")
 set.segments = 20
 dynamics_type = DYNAMIC
 ```
+
 Then, we define vectors of the system structure types we are going to use. For this simple example we only need points and segments.
+
 ```julia
 points = Point[]
 segments = Segment[]
 
-points = push!(points, Point(1, [0.0, 0.0, set.l_tether], STATIC; wing_idx=0))
+points = push!(points, Point(1, zeros(3), STATIC; wing_idx=0))
 ```
+
 The first point we add is a static point. There are four different [`DynamicsType`](@ref)s to choose from: `STATIC`, `QUASI_STATIC`, `DYNAMIC` and `WING`. `STATIC` just means that the point doesn't move. `DYNAMIC` is a point modeled with acceleration, while `QUASI_STATIC` constrains this acceleration to be zero at all times. A `WING` point is connected to a rigid wing body.
 
 Now we can add `DYNAMIC` points and connect them to each other with segments. `BRIDLE` segments don't need to have a tether, because they have a constant unstretched length.
@@ -35,28 +38,35 @@ segment_idxs = Int[]
 for i in 1:set.segments
     global points, segments
     point_idx = i+1
-    pos = [0.0, 0.0, set.l_tether] - set.l_tether / set.segments * [0.0, 0.0, i]
+    pos = [0.0, 0.0, i * set.l_tether / set.segments]
     push!(points, Point(point_idx, pos, dynamics_type; wing_idx=0))
     segment_idx = i
     push!(segments, Segment(segment_idx, (point_idx-1, point_idx), BRIDLE))
     push!(segment_idxs, segment_idx)
 end
 ```
-From these arrays of points and segments we can create a [`SystemStructure`](@ref), which can be plotted in 2d to quickly investigate if the model is correct.
+
+In order to describe the initial orientation of the structure, we define a [`Transform`](@ref) with an elevation (-80 degrees), azimuth and heading, and a base position `[0.0, 0.0, 50.0]`.
+```julia
+transforms = [Transform(1, deg2rad(-80), 0.0, 0.0, [0.0, 0.0, 50.0], points[1].idx; 
+                            rot_point_idx=points[end].idx)]
+```
+
+From the points, segments and transform we create a [`SystemStructure`](@ref), which can be plotted in 2d to quickly investigate if the model is correct.
 ```julia
-sys_struct = SystemStructure("tether"; points, segments)
+sys_struct = SystemStructure("tether", set; points, segments, transforms)
 plot(sys_struct, 0.0)
-plt.gcf()
 ```
+![SystemStructure visualization](tether_sys_struct.png)
 
 If the system looks good, we can easily model it, by first creating a [`SymbolicAWEModel`](@ref), initializing it and stepping through time.
 ```julia
-model = SymbolicAWEModel(set, sys_struct)
+sam = SymbolicAWEModel(set, sys_struct)
 
-init_sim!(model; remake=false)
-for i in 1:100
-    plot(model, i/set.sample_freq)
-    next_step!(model; dt=1/set.sample_freq)
+init_sim!(sam; remake=false)
+for i in 1:80
+    plot(sam, i/set.sample_freq)
+    next_step!(sam)
 end
-plt.gcf()
 ```
+![Tether during simulation](tether_during_sim.png)

docs/src/ram_air_kite.md

@@ -47,8 +47,8 @@ toc()
 # plot(sam.sys_struct, 0.0; zoom=false, front=false)
 
 # Initialize at elevation
-sam.sys_struct.winches[2].tether_length += 0.2
-sam.sys_struct.winches[3].tether_length += 0.2
+set.l_tethers[2] += 0.2
+set.l_tethers[3] += 0.2
 init_sim!(sam; remake=false, reload=false)
 sys = sam.sys
 
@@ -63,7 +63,7 @@ sys_state = SysState(sam)
 t = 0.0
 runtime = 0.0
 integ_runtime = 0.0
-bias = set.quasi_static ? 0.45 : 0.35
+bias = set.quasi_static ? 0.45 : 0.40
 t0 = sam.integrator.t
 
 try
@@ -147,3 +147,5 @@ p = plotx(sl.time,
 display(p)
 
 @info "Performance:" times_realtime=(total_time/2)/runtime integrator_times_realtime=(total_time/2)/integ_runtime
+
+# 55x realtime (PLOT=false, CPU: Intel i9-9980HK (16) @ 5.000GHz)