Init interface (#242)

* Set the integrator

* Add tests for KPS3 and KPS4

* Allow param stiffness and delta

* more tests

* More changes, tests fail

* Fix tests

* Rename init_sim! to init!

* Update changelog

* Update CHANGELOG.md

* Fix typo

* Fix test

* Next try

* Next try

* Add comment

* Update section initial

* Cleanup

* Longer dt

* Increase abstol

* next try

* Next try

* Add Build PyCall

* Disable Steering Response Using SysState

---------

Co-authored-by: Uwe Fechner <[email protected]>
Co-authored-by: 1-Bart-1 <[email protected]>

Author: ufechner7

.github/workflows/CI.yml

@@ -133,6 +133,9 @@ jobs:
         shell: bash
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
+      - name: Build PyCall
+        run: julia --project=docs/ -e 'ENV["PYTHON"]=""; using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); Pkg.build("PyCall")'
+        shell: bash
       - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-docdeploy@v1

CHANGELOG.md

@@ -2,9 +2,18 @@
 SPDX-FileCopyrightText: 2025 Uwe Fechner, Bart van de Lint
 SPDX-License-Identifier: MIT
 -->
+### Unreleased
+#### Changed
+- rename `init_sim!` to `init!`
+- removed the parameter `upwind_dir!` from `init!`; use set.upwind_dir instead. Careful: This is in degrees.
+- the function `init!` accepts (and ignores) the parameters `delta` and `stiffness_factor` if applied to a 
+  SymbolicAWEModel
+### Added
+- add the test script test_interface.jl
+- add the field `integrator` to KPS4 and KPS3 structs
 
 ### KiteModels v0.8.1 2025-06-20
-#### CHANGED
+#### Changed
 - renamed POWER to POWER_LINE and STEERING to STEERING_LINE
 - improved documentation, fixed example
 

data/settings.yaml

@@ -11,10 +11,18 @@ system:
     fixed_font: ""                 # name or filepath+filename of alternative fixed pitch font, e.g. Liberation Mono
 
 initial:
-    l_tethers: [150.0, 0, 0]       # initial tether length       [m]
-    elevation: [70.8]              # initial elevation angle   [deg]
-    v_reel_outs: [0.0, 0 ,0]       # initial reel out speed    [m/s]
-    depower:     [25.0]            # initial depower settings    [%]
+    elevations: [70.8]               # initial elevation angle   [deg]
+    elevation_rates: [0.0]           # initial elevation rate  [deg/s]
+    azimuths: [0.0]                  # initial azimuth angle     [deg]
+    azimuth_rates: [0.0]             # initial azimuth rate    [deg/s]
+    headings: [0.0]                  # initial heading angle     [deg]
+    heading_rates: [0.0]             # initial heading rate    [deg/s]
+    # three values are only needed for RamAirKite, for KPS3 and KPS4 use only the first value
+    l_tethers: [150.0]               # initial tether lengths      [m]
+    kite_distances: [51.0]           # initial kite distances     [m]
+    v_reel_outs: [0.0]               # initial reel out speeds   [m/s]
+    depowers: [25.0]                 # initial depower settings    [%]
+    steerings: [0.0]                 # initial steering settings   [%]
 
 solver:
     abs_tol: 0.0006        # absolute tolerance of the DAE solver [m, m/s]

docs/src/examples_4p.md

@@ -30,7 +30,7 @@ Then we call the function `find_steady_state` which uses a non-linear solver to
 find_steady_state!(kps, prn=true)
 ```
 Finding the steady state of the 4-point model is difficult and it only works when we artificially reduce the stiffness by a factor
-of 0.035. In the function [`init_sim!`](@ref) this factor is slowly increased to 1.0.
+of 0.035. In the function [`init!`](@ref) this factor is slowly increased to 1.0.
 
 To plot the result in 2D we extract the vectors of the x and z coordinates of the tether particles with a for loop:
 ```julia

docs/src/functions.md

@@ -55,7 +55,7 @@ SysState
 
 ## High level simulation interface
 ```@docs
-init_sim!
+init!
 next_step!
 ```
 

docs/src/index.md

@@ -83,7 +83,7 @@ times faster.
 - the documentation was improved
 
 ## Provides
-The types [`KPS3`](@ref), [`KPS4`](@ref) and [`SymbolicAWEModel`](@ref), representing the one point, the four point kite model and the ram air kite model, together with the high level simulation interface consisting of the functions [`init_sim!`](@ref) and [`next_step!`](@ref). Other kite models can be added inside or outside of this package by implementing the non-generic methods required for an AbstractKiteModel.
+The types [`KPS3`](@ref), [`KPS4`](@ref) and [`SymbolicAWEModel`](@ref), representing the one point, the four point kite model and the ram air kite model, together with the high level simulation interface consisting of the functions [`init!`](@ref) and [`next_step!`](@ref). Other kite models can be added inside or outside of this package by implementing the non-generic methods required for an AbstractKiteModel.
 
 Additional functions to provide inputs and outputs of the model on each time step. In particular the constructor [`SysState`](@ref) can be called once per time step to create a SysState struct for
 logging or for displaying the state in a viewer. For the KPS3 and KPS4 model, once per time step the [`residual!`](@ref) function is called as many times as needed to find the solution at the end

docs/src/tutorial_system_structure.md

@@ -69,7 +69,7 @@ If the system looks good, we can easily model it, by first creating a [`Symbolic
 ```julia
 sam = SymbolicAWEModel(set, sys_struct)
 
-init_sim!(sam; remake=false)
+init!(sam; remake=false)
 for i in 1:80
     plot(sam, i/set.sample_freq)
     next_step!(sam)

examples/bench.jl

@@ -34,7 +34,7 @@ function simulate(integrator, steps)
     iter / steps
 end
 
-integrator = KiteModels.init_sim!(kps4; delta=0, stiffness_factor=0.5, prn=STATISTIC)
+integrator = KiteModels.init!(kps4; delta=0, stiffness_factor=0.5, prn=STATISTIC)
 
 println("\nStarting simulation...")
 simulate(integrator, 100)

examples/bench_4p.jl

@@ -52,7 +52,7 @@ function simulate(integrator, steps, offset=0)
     iter / steps
 end
 
-integrator = KiteModels.init_sim!(kps4, delta=0, stiffness_factor=0.5, prn=STATISTIC)
+integrator = KiteModels.init!(kps4, delta=0, stiffness_factor=0.5, prn=STATISTIC)
 
 println("\nStarting simulation...")
 simulate(integrator, 100, 100)

examples/calc_spectrum.jl

@@ -100,7 +100,7 @@ function sim_and_plot(set; depower=DEPOWER, f_ex)
     set.elevation = 67.0
     kcu::KCU = KCU(set)
     kps4::KPS4 = KPS4(kcu)
-    integrator = KiteModels.init_sim!(kps4; delta=0.001*0, stiffness_factor=1, prn=STATISTIC)
+    integrator = KiteModels.init!(kps4; delta=0.001*0, stiffness_factor=1, prn=STATISTIC)
     set_depower_steering(kps4.kcu, depower, 0.0)
     simulate(kps4, integrator, logger, STEPS, f_ex)
     save_log(logger, "tmp")