Make find_steady_state! for KPS3 find a real equilibrium

[ufechner7]

Problem

The steady-state solver of KPS3 almost never found an equilibrium. nlsolve reported "converged" only because its steps became tiny (x_converged). The accelerations of the tether particles were still about 25 m/s², and the tether stayed nearly straight. On some machines (e.g. the GitHub runners) one of the two passes ran into the 1000-iteration limit and printed:

Warning: find_steady_state!: solver did not converge! (f_converged=false, x_converged=false, iterations=1000)

Causes:

• Bad conditioning: the unknowns were Cartesian offsets of the particle positions. The Jacobian had 6 large singular values (~1e5, stretching the segments) and 6 tiny ones (0.1–1, rotating them), so plain Newton steps diverged.
• Kink at the start: the solver started from the unstretched tether, exactly at the kink of the spring force between tension and compression.
• Over-determined kite: the kite can only be fully balanced at its natural elevation, which can be far from set.elevation.

Change

• New unknowns: the angles of the tether segments relative to the elevation angle and their relative stretches. They are converted to the offsets that init uses.
• Start point: the solver starts from a straight tether stretched by 0.1%.
• Prescribed elevation (as for KPS4 in 0.11.18): the elevation of the kite is prescribed instead of its vertical force balance. The tether particles (x and z) and the horizontal balance of the kite are solved to ftol = 1e-6, and calc_elevation(s) returns set.elevation.
• Independent of upwind_dir: the horizontal residuals and positions are taken in the plane of the tether.
• Fallback: if the pass with reduced stiffness fails, the full-stiffness pass starts again from the straight tether. A warning is printed only if the final pass fails.
• CHANGELOG entry under 0.11.19 (still unreleased).

The initial state changes. For the 392 m case in test-kps3.jl the kite now starts at 70.0° instead of its natural elevation of 64.3°, so the expected tether length, forces and lift/drag are updated.

Tests

• test_find_steady_state now checks that no warning is logged, the elevation, and that the tether particles and the kite's horizontal balance are in equilibrium. It no longer skips failures on CI. With the old solver, 6 of its tests fail.
• Full suite locally (Julia 1.13): 651 passed, 11 broken (existing @test_broken).
• The solver converges, with the elevation exactly as configured, for: system.yaml; the 392 m case; upwind_dir 0°, 45°, 180°; v_wind 3, 6.5, 12, 20 m/s; elevation 20°, 45°, 85°; 12 segments. Before, elevation 20°/45° and v_wind 20 m/s did not converge.
• A 20 s simulation with system.yaml and with the parking_1p settings of KiteControllers.jl behaves like before.

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

🟡 Changes recommended

The advertised direction-independent equilibrium behavior lacks automated coverage for non-default wind directions.

1 open finding

• Test coordinate transform across representative upwind directions · New

What changed in this PR

Improves KPS3 steady-state initialization by using better-conditioned segment angles and stretches while prescribing kite elevation.

Changes:

• Reworks equilibrium variables, convergence handling, and fallback behavior.
• Updates KPS3 equilibrium assertions and expected initial-state values.
• Documents the corrected initialization behavior.

File	Description
src/​KPS3.jl	Implements the revised steady-state solver.
test/​test-kps3.jl	Updates equilibrium tests and expected values.
CHANGELOG.md	Describes the solver correction.

🧠 Review effort: Balanced

---

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