Add trim option, deprecate delta and stiffness_factor, fix steady-state wind and reel-out velocities

[ufechner7]

Summary

• New: find_steady_state!(s; trim=true) (KPS3 and KPS4). Instead of prescribing set.elevation, the vertical force balance of the kite is solved too, so the kite is placed at the elevation where its lift matches gravity. The default trim=false keeps the previous behaviour.
• New: init!(s; trim=true) passes trim through to find_steady_state!. The initial state is then an equilibrium of the simulation, so the elevation stays constant.
• KPS4 trim balances gravity. KPS4's init sets the vertical accelerations in yd0 to -g, so the steady-state solver balances the forces without gravity (the existing sum(res2) ≈ -9.81*N tests rely on this for trim=false, which is unchanged). With trim=true the accelerations are zero, so the kite is trimmed with its weight. KPS3 already balanced gravity.
• Deep stall trims are rejected. A second, fully balanced trim exists at low elevations with the kite in deep stall. Trimmed solutions with an angle of attack beyond the angle of maximum lift (from alpha_cl/cl_list) are rejected. KPS4 starts the trim search at 80° (or at set.elevation, if higher), because the solver converges from above the natural elevation but often not from far below it. If no valid trim is found, the solver is restarted at other elevations in steps of 10°, with a cheaper solve (no perturbation, no last-resort continuation). If no attached-flow trim is found at all, find_steady_state! throws an error instead of returning a deep-stall or non-converged state, and init!(s; trim=true) prints the reason and returns nothing. With system.yaml and the Maasvlakte profile at 4 m/s, where no such trim exists, failing takes 7 s (KPS3) and 11 s (KPS4).
• delta is deprecated and ignored (find_steady_state! and init!). It perturbed the initial state, and the returned state was perturbed too, so it wasn't an equilibrium. Now the steady state is solved without perturbation, with delta = 0.001 only as an internal fallback, and always returned unperturbed.
• stiffness_factor is deprecated and ignored (find_steady_state! and init!). Before, the KPS4 steady state was solved for the reduced tether stiffness stiffness_factor, which next_step! then raised by 0.01 per step to 1.0, so the initial state was not an equilibrium of the simulation and depended on the chosen value. Now the steady state is always solved for the full stiffness (s.stiffness_factor == 1.0 afterwards). A reduced stiffness is only used internally as start value: if the direct solve fails, the schedules 0.1 → 1, 0.1 → 0.3 → 1 and 0.3 → 1 are tried, then the previous continuation (see Solver strategy). For KPS3 the first solve uses a fixed 0.035; its result was already solved for the full stiffness.
• Warning for deep stall at a prescribed elevation. With trim=false, a prescribed elevation far below the natural one can only be balanced in deep stall; this was returned silently. find_steady_state! now warns and suggests trim=true or a higher elevation. With system.yaml this happens below about 45° for KPS4 and 65° for KPS3.
• Fix (KPS4): steady state used the ground wind. The wind was set once from the kite height before solving, which is 0 m after clear!, so the kite was balanced for 9.51 m/s instead of 12.6 m/s. The wind is now set from the kite height of every solver iterate.
• Fix (KPS4): wrong initial reel-out velocities. The particle velocities were multiplied by the segment length (about 25 m), and the KCU direction came from the bridle: with v_reel_out = 1 m/s the KCU started at 20.9 m/s and the kite at 5.0 m/s. With trim=true the kite was placed at 54.8° instead of 68.2° (examples/test_init_4p.jl) and then climbed for about 10 s, with a tether force peak of more than twice the steady value. Now each particle moves along its segment, growing linearly to v_reel_out at the KCU.
• Fix (KPS3): v_reel_out was ignored in the steady state. All particles were at rest and the reel-out speed in the initial state was zero, so the initial elevation didn't depend on v_reel_out and the winch first had to accelerate. Now the particle velocities grow linearly to v_reel_out at the kite, and the state starts with the reel-out speed. With trim=true at 14.5 m/s: 73.5° at 0 m/s, 70.4° at 1 m/s, 60.9° at 4 m/s, constant during the simulation.
• Examples: no longer pass delta or stiffness_factor; test_init_1p.jl and test_init_4p.jl use trim=true and print v_reel_out; compare_kps3_kps4.jl uses the same x limits for all frames (the kite seemed to jump after the first frame). The examples use MakieControlPlots from its main branch.

Solver strategy

Benchmark of nlsolve alone (without the elevation restarts) for KPS4 with system.yaml: 160 cases (wind 6–25 m/s, elevation 40–85°, tether 50–1000 m, with and without trim), of which 119 were solvable by at least one strategy. Failures among those 119:

Strategy	Failures (fixed elevation / trim)	Total time
1.0 directly	14 / 12	12.4 s
0.1 → 1.0	25 / 3	13.5 s
1.0, else 0.1 → 1.0	5 / 3	15.1 s
1.0, else 0.1→1, 0.1→0.3→1, 0.3→1	2 / 1	17.1 s
adaptive continuation from 0.1	24–32 / 3	19–28 s
previous continuation, target 1.0	2 / 0	22.9 s

Starting directly at 1.0 is fastest and works for most fixed-elevation cases, starting at 0.1 is needed mainly for trim, and the schedule chain and the previous continuation fail in different cases. All 41 unsolved cases were trims started at 40° or 55°. The chain, then the previous continuation, with the trim search starting at 80° solved all 160 cases, in 0.14 s on average (max. 1.2 s). With 12 segments: 0.6 s on average; 4 trim cases at 6 m/s and 50 m tether failed in the benchmark (in production the elevation restarts follow).

With the production find_steady_state! (including restarts) on the same 160 cases: KPS4 solves all, 24.9 s in total (max. 2.7 s); KPS3 solves 156, the 4 failures are fixed-elevation cases (trim=false) at 20–25 m/s, 40–55° and 400–1000 m tether, which the trim changes don't touch.

Behaviour changes

• Initial states of KPS4 change for everyone: the wind fix changes them for trim=false too (with system.yaml the winch force after find_steady_state! goes from 308 N to 456 N), and the tether is now only stretched as much as the full stiffness allows.
• Initial states change for both models for runs with v_reel_out ≠ 0 (velocity fixes), and slightly for runs that used delta > 0 (including init!'s former default of 0.005).
• Code that passes delta or stiffness_factor keeps working, with a Base.depwarn. KiteControllers.jl still passes both.
• With trim=true, a case without an attached-flow trim now raises an error in find_steady_state! (and init! returns nothing); before, a deep-stall state was returned with a warning.

Performance

find_steady_state!(s; trim=true) for KPS4 takes 0.04–0.09 s, independent of set.elevation (10°, 30°, 55°, 70.8°, 85° tested); before, KPS4 started far below the trim needed restarts that took 12–45 s. The Trim testset went from 21 s to 2–3 s.

Tests

• New test/test-trim.jl: both models, starts at 30°, 55° and 85°, all forces balanced to < 1e-4, no deep stall, no warnings, result independent of the start value, and the elevation stays constant after init!(s; trim=true); wind profiles Maasvlakte (EXPLOG) and Cabauw (EXP) at 4, 7 and 10 m/s (Maasvlakte at 4 m/s skipped: no attached-flow trim exists); delta and stiffness_factor are accepted and ignored; at a prescribed 40°, trim=false warns about deep stall and trim=true finds an attached-flow trim; with v_reel_out = 2 m/s the initial state contains the reel-out speed and the trimmed elevation is lower than at 0 m/s; for the Maasvlakte profile at 4 m/s (no attached-flow trim) find_steady_state! throws and init! returns nothing.
• test/test-steady-state-robustness.jl: cases at 50° moved to 60° and 65°; the per-case stiffness factor is removed and the test checks stiffness_factor == 1.0 afterwards.
• Raptures test (test-kps4.jl): stiffness raised to 20 instead of 3 to break the bridle, because the initial state is now at full stiffness.
• Full test suite (runtests.jl) passes locally on Julia 1.13 (1 min 34 s); test-trim.jl alone: 112/112. Of the examples, only compare_kps3_kps4.jl was run.

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

❌ Patch coverage is 89.70588% with 14 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/KPS4.jl	84.61%	12 Missing ⚠️
src/KPS3.jl	95.65%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

🟡 Changes recommended

Both trim solvers can still return an invalid deep-stall or unconverged state after failing to find the promised attached-flow equilibrium.

6 open findings

• Report failure when attached-flow restarts all fail · New
• Fail trim when no attached-flow restart succeeds · New
• Remove deprecated stiffness_factor from example · New
• Remove deprecated stiffness_factor from example · New
• Remove deprecated stiffness_factor from example · New
• Qualify equilibrium guarantee when steady state is disabled · New

What changed in this PR

Adds natural-elevation trimming to KPS3/KPS4 while correcting steady-state wind, reel-out velocity, and tether-stiffness initialization.

Changes:

• Adds trim=true, attached-flow checks, and solver restart strategies.
• Deprecates delta and stiffness_factor; initializes at full stiffness.
• Updates tests, examples, documentation, and release notes.

File	Description
src/​KPS3.jl	Adds trimming and reel-out-aware initialization.
src/​KPS4.jl	Adds trimming, wind updates, continuation, and velocity fixes.
src/​KiteModels.jl	Adds shared options, deprecations, and init! integration.
src/​precompile.jl	Updates precompile calls.
test/​test-trim.jl	Tests trimming, profiles, deprecations, and reel-out.
test/​test-steady-state-robustness.jl	Updates full-stiffness robustness cases.
test/​test-steady-state-kps4.jl	Removes deprecated arguments.
test/​test-winch-state.jl	Uses default initialization.
test/​test-update-sys-state.jl	Removes deprecated options.
test/​test-simulate_4p.jl	Updates initialization.
test/​test-kps4.jl	Updates steady-state and breakage tests.
test/​test-kps3.jl	Updates steady-state calls.
test/​test-interface.jl	Updates interface tests.
test/​test_for_precompile.jl	Updates precompile test initialization.
test/​plot_kps4.jl	Updates plotting setup.
examples/​Project.toml	Sources MakieControlPlots from main.
examples/​test_steady_state.jl	Removes deprecated options.
examples/​test_init_4p.jl	Demonstrates trimmed KPS4 initialization.
examples/​test_init_1p.jl	Demonstrates reel-out-aware KPS3 trim.
examples/​steering_test_4p.jl	Updates initialization.
examples/​steering_test_1p.jl	Updates initialization.
examples/​simulate_steering.jl	Updates initialization.
examples/​simulate_simple.jl	Updates non-steady initialization.
examples/​reel_out_4p.jl	Updates initialization.
examples/​reel_out_4p_torque_control.jl	Updates initialization.
examples/​reel_out_1p.jl	Updates initialization.
examples/​plot_side_cl.jl	Updates initialization.
examples/​plot_pitch_stability.jl	Updates initialization.
examples/​plot_parking_test.jl	Updates initialization.
examples/​plot_cl_cd.jl	Updates initialization.
examples/​plot_alpha2.jl	Updates initialization.
examples/​compare_kps3_kps4.jl	Stabilizes plot limits and updates initialization.
examples/​calc_spectrum.jl	Updates initialization.
examples/​bench.jl	Updates KPS3 benchmark setup.
examples/​bench_4p.jl	Updates KPS4 benchmark setup.
examples_3d/​parking_wind_dir.jl	Partially removes deprecated options.
examples_3d/​parking_4p.jl	Partially removes deprecated options.
examples_3d/​auto_parking_4p.jl	Partially removes deprecated options.
docs/​src/​examples_4p.md	Removes obsolete stiffness explanation.
CHANGELOG.md	Documents trim, deprecations, and fixes.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.