Settings and data files

load_yaml_fields!(obj, filename, section; path = skc_data_path()) -> obj

Set every field section (a top-level key in the YAML file filename) names on the mutable struct obj, converting each value to the field's declared type; filename is resolved under path unless already absolute. An unknown key errors, a key the file omits leaves obj's existing value (its struct default, for a freshly constructed obj) untouched. A key in RETIRED_YAML_KEYS is skipped if it has the value listed there and errors otherwise, so archived settings files still load.

Purely reflective (hasfield/setfield!/fieldtype on typeof(obj)), so it works on any mutable struct without src/ depending on the struct's package. FC_Settings is built on it. It also loaded WinchControllers.jl's WCSettings in examples/simple_reelout.jl until the 2026-08-16 winch merge gave that struct a single file reached through the project's wc_settings: key (PlanWinchcontrol.md), which is V3Kite's WC_Settings(filename)'s job now.

apply_overrides!(obj, overrides, label, typename, what)

Set each key => value of overrides as a field of the settings struct obj, converted to the field's type, and log the ones in force as "what overrides in force". label is the name of the input that carried them and typename the type's name, both for the error of a key that is not a field of obj. For an FC_Settings, a key is a setting by its bare name, in whichever part holds it (set_fc_field!).

set_fc_field!(fcs::FC_Settings, key::Symbol, value) -> fcs

Set the part key of fcs, or the setting key in whichever part holds it (FC_FIELD_PART), converting value to the field's type. Errors for a key that is neither.

get_fc_field(fcs::FC_Settings, key::Symbol)

The setting key of fcs by its bare name, from whichever part holds it (FC_FIELD_PART); the counterpart of set_fc_field!.

set_tos_field!(tos::TrajOptSettings, key::Symbol, value) -> tos

Set the part key of tos, or the setting key in whichever part holds it (TO_FIELD_PART), converting value to the field's type. Errors for a key that is neither.

get_tos_field(tos::TrajOptSettings, key::Symbol)

The setting key of tos by its bare name, from whichever part holds it (TO_FIELD_PART); the counterpart of set_tos_field!.

skc_data_path() -> String

Absolute path of this package's bundled data/ directory, holding fc_settings.yaml (FC_Settings), turn_rate_coeffs.yaml (turn_rate_coeffs), winch_table.yaml (winch_f_low) and the system project of a run (project_file).

Not KiteUtils.get_data_path(): that points at the kite model's data directory during a run, while these settings belong to the controller.

project_file(project = "system_fig8_200m.yaml") -> String

Path of the system project to hand to the kite model, absolute when this package carries it in skc_data_path and unchanged otherwise, which leaves it a lookup under the active data path.

The absolute form is what makes sim_settings this package's file: KiteUtils resolves it relative to the project. Bare names like wc_settings instead follow the active data path, which examples/simple_fig8.jl also points here.

Not a field of FC_Settings: which plant a run is flown against is not a tuning parameter of the controller.

turn_rate_coeffs_file(project = project_file()) -> String

Get the turn-rate table filename from the system project, the same way as fc_settings. Returns the value of the turn_rate_coeffs field of the project's system section; present in every project.

course_loop_model_file(project = project_file()) -> String

Get the filename of the identified course-loop model (CourseLoopModel) from the system project, the same way as fc_settings. Returns the value of the course_loop_model field of the project's system section; present in every project.

kite_correction_file(project = project_file()) -> String

Get the filename of the measured kite correction (written by examples/identify_kite_correction.jl, read with load_course_correction) from the system project, the same way as fc_settings. Returns the value of the kite_correction field of the project's system section; present in every project.

winch_table_file(project = project_file()) -> String

Get the winch table filename from the system project, the same way as fc_settings. Returns the value of the winch_table field of the project's system section; only reel-out projects carry it.

traj_opt_settings_file(project = project_file()) -> String

Get the trajectory-optimizer settings filename from the system project, the same way as fc_settings. Returns the value of the traj_opt_settings field of the project's system section; present in every project that flies against an externally optimized path (both fig8 and reel-out).

The menu's state file, data/gui.yaml of this package (see GUI_STATE_FILE_OVERRIDE)

ensure_gui_state_file() -> String

The path of gui_state_file, created from its .default copy if it does not exist yet.

read_gui_field(name) -> Union{String, Nothing}

The value of the scalar name: in data/gui.yaml, unquoted, or nothing when the key is missing or empty.

write_gui_field(name, value)

Set the scalar name: in data/gui.yaml to value, adding it under gui: when it is missing; line-based, so every other key and comment is kept.

The system project the figure-of-eight scripts fly without a selection

The system project the reel-out scripts fly without a reel-out selection

The plots shown without a selection

selected_project() -> String

Currently selected system project file name, falling back to default_project if gui.yaml has no project: entry.

selected_reelout_project() -> String

Project the simple_reelout*.jl scripts fly: the persisted selection when it already names a reel-out project (system_reelout_*.yaml), otherwise default_reelout_project.

project: is a single shared key, so without this a fig8 selection left over from simple_fig8.jl would run the reel-out scripts against that project's fc_settings.yaml, whose compliance: 0.5 (FORCE mode) simple_reelout.jl rejects at startup. Falling back here keeps both families runnable without re-selecting in between, while select_project() still decides between several reel-out projects once there is more than one.

selected_fig8_project() -> String

Project the figure-of-eight scripts (simple_fig8.jl, stability_fig8.jl) fly: the persisted selection when it already names a fig8 project (system_fig8_*.yaml), otherwise default_project.

The counterpart of selected_reelout_project: a reel-out selection left over from simple_opt_reelout.jl would otherwise run these scripts against a reel-out project's fc_settings.yaml.

selected_sim_time() -> Union{Float64, Nothing}

Persisted simulation-time override in seconds, or nothing for the default choice (the selected project's own sim_time).

selected_plots() -> Vector{String}

Persisted set of plots simple_fig8_plots.jl shows, falling back to default_plots (all of them) if gui.yaml has no plots: entry.

selected_windspeed() -> Union{Float64, Nothing}

Persisted wind-speed override in m/s at the project's reference height, or nothing for the default choice (the selected project's own v_wind). Pass something(selected_windspeed(), project_set.v_wind) to init.

selected_turbulence() -> Union{Float64, String, Nothing}

Persisted turbulence level init applies, or the "default" keyword when the settings YAML stays in charge. Pass it straight to init's use_turbulence. Read here rather than through V3Kite's get_default_turbulence so that picking a project does not pull the kite model into the session.

set_selected_project(project::String)

Persist project as the current selection, keeping the other entries unchanged.

set_selected_sim_time(sim_time::Union{Real, Nothing})

Persist sim_time (seconds, or nothing for default) as the current selection, keeping the other entries unchanged.

set_selected_plots(plots::Vector{String})

Persist plots (a subset of default_plots) as the current selection, keeping the other entries unchanged.

set_selected_windspeed(wind_speed::Union{Real, Nothing})

Persist wind_speed (m/s, or nothing for default) as the current selection, keeping the other entries unchanged.

apply_windspeed_override!(project_set, wind_speed::Union{Real, Nothing})

Overwrite project_set's wind speed with wind_speed [m/s], keeping its direction and elevation. A no-op for nothing (the default choice).

project_set.v_wind = wind_speed alone only works when the project has use_wind_vec: false: KiteUtils.Settings re-derives v_wind from wind_vec on every property write when use_wind_vec is true (all of this package's settings files set it), so a plain v_wind assignment is silently reverted by that same write. Setting wind_vec instead — at the project's existing upwind_dir/upwind_elevation — keeps both representations consistent regardless of which one is authoritative.

scenario_site(project = selected_reelout_project()) -> String

The site subfolder of output/scenarios/ a reel-out project's runs are archived under: "cabauw" for system_reelout_cabauw.yaml, "maasvlakte" for every other reel-out project. move_scenario.jl files a run by the project its summary YAML records; the readers (plot_scenario.jl, plot_powercurve.jl, create_plots.jl) pass nothing and follow the active project, see selected_scenarios_dir.

selected_scenarios_dir() -> String

output/scenarios/<site> for the active reel-out project's site (see scenario_site): the folder move_scenario.jl files that project's runs into, and the one the scenario readers list.