Winch

winch_f_low(v_wind; project = project_file()) -> Float64

Wind-speed-dependent force floor [N] below which WinchControllers.jl's LowerForceController reels in, from the f_low column of the project's winch_table file (see winch_table_lookup). Overrides the flat f_low of data/wc_settings.yaml; the caller assigns the result to WCSettings.f_low.

It is wind-dependent because the two things it sits between scale differently: the winch's rating does not move with the wind, while the force a kite can produce goes with its square. A single value sized for strong wind takes over the run in weak wind — measured at 3 m/s, f_low 700 N put the limiter in control 63 % of the time against 21 % at 350 N. NOT the entry guard's floor, which is FC_Settings.winch.entry_f_min; see docs/fig8_tuning_log.md.

winch_force_limit(v_wind; project = project_file()) -> String

Wind-speed-dependent WCSettings.force_limit, "hard" or "soft", from the force_limit column of the project's winch_table file (see winch_table_select). Overrides the flat value of data/wc_settings.yaml, which is "hard" so that a script not consulting this table gets the safe law.

It has to be wind-dependent because the soft law is only DEFINED over part of the range. It inverts the optimizer's tension curve, whose effective floor is sp(beta*f_low)/beta — 884 N at f_low 350 — and at beta 1e-3 that floor cannot go below ln(2)/beta = 693 N for ANY f_low. The whole 3 m/s force range is 587 +- 165 N, i.e. below the floor, where the law commands a standstill and the run reels in instead of out. Raising beta to move the floor is CLOSED: 2e-3 and 5e-3 both make the 3 m/s solve fail outright. So low wind gets the hard law, and the soft law is used where it was measured — see docs/fig8_tuning_log.md.

winch_table_lookup(v_wind, key; project = project_file()) -> Float64

Linearly interpolate column key of the system project's winch_table file (winch_table_file) against mean wind speed. Clamped to the lowest/highest identified wind speed outside that range, never extrapolated. Only reel-out projects carry a winch_table entry, so calling this against a fig8 project throws, as does a table missing key in any row.

winch_table_select(v_wind, key; project = project_file()) -> Any

Step-lookup of column key: the value of the LAST row at or below v_wind, clamped to the first row below the identified range. The counterpart of winch_table_lookup for columns that cannot be interpolated — a setting is one thing or another at a given wind speed, never 40 % of the way between them.

load_wc_settings(filename; dt) -> WCSettings

Load winch-controller settings from the YAML file filename, looked up under the active data path (joinpath(get_data_path(), filename)) unless absolute. The file must have a top-level wc_settings: mapping whose keys are fields of WCSettings; a missing key keeps the struct default, an unknown key errors.

This used to be V3Kite's own WC_Settings(filename). It lives in SimpleKiteControllers now because the struct belongs to WinchControllers.jl and the file belongs to the run — V3Kite itself no longer reads winch gains at all. dt always wins over the file's placeholder value: it is the plant's timestep, not a tuning choice.

build_winch(project, project_set, fcs) -> (; wc, wpc, dt0)

The winch settings and the length loop of the run. ONE WCSettings (wc) serves BOTH winch loops, the POSITION-mode torque gains (wpc) and the speed-controller tuning of the reel-out controller, so the wind-dependent force floor and force-limit law of the project's tables are set on it here. Refuses a compliance other than 0: REEL_OUT and V3Kite's own FORCE mode both drive the winch, and only one can hold the drum at a time.

build_controllers(fcs, rcs, s) -> (; rc, f_high_nominal, stop_criteria, guard_lfc, l_set, fec)

The controllers of the run, built on the settled model s: the reel-out winch controller rc (built after init, so its soft-start ramp begins when reel-out starts; rcs is the one WCSettings of both winches), the nominal force ceiling f_high_nominal captured before the first-lap reduction (winch_from_wc sends this one to the optimizer), the standalone force-floor guard for phases 0-2 (rc's own SpeedController would wind up while its output is ignored), the length setpoint l_set (the settled length, growing from phase 3 until it reaches reelout_l_max) and the figure-of-eight controller fec.

Of the model it reads only s.dt and s.sys_state.l_tether, so it takes any plant.

winch_force_gains(fcs::FC_Settings, wcs) -> NamedTuple

The force-mode winch gains of the winch settings wcs (a WCSettings, loaded from the project's wc_settings.yaml) with the compliance of fcs applied, as a NamedTuple keyed to match a force-mode winch controller's fields (force_tau, len_kp, damp, force_min). Splat it into whichever winch the kite model provides:

wfc = WinchForceController(; winch_force_gains(fcs, wcs)...)

wcs.winch_len_kp and wcs.winch_damp are both divided by fcs.winch.compliance, so the yield scales linearly with it while their ratio — the length loop's own time constant — is unchanged. wcs.winch_force_tau is passed through untouched: it sets WHICH frequencies the drum yields to, not by how much.

Plain numbers on purpose. The scaling is the part worth keeping in this package; the controller object it feeds belongs to the kite model, which this package does not depend on.

Errors at compliance == 0: that is position mode and must not be flown through a force-mode winch (an infinitely stiff spring is not representable — see FC_Settings).