AWETrim: Instructions file for Codex

AWETrim — Agent Context

What this repo is

AWETrim is a Python library for the design and optimisation of soft-kite Airborne Wind Energy Systems (AWES). It models the kite as a point mass in a course-aligned spherical reference frame, provides CasADi-based trajectory optimisation, and implements the winch/tether physics for pumping-cycle simulation.

Module status

src/awetrim/
  system/            ✅  Wing, Kite, SystemModel, Winch, Tether variants
                         (rigid/flexible link, rigid/flexible lumped,
                          Williams discretised distributed-mass)
  aerodynamics/      ✅  VSM quasi-steady trim + KCU bluff-body drag
                         (kcu_drag.py, single-sourced, on by default in the
                          aerostructural path via is_with_kcu_drag)
                         + bridle-line SECTION drag (line_drag.py): the
                         steering/depower lines are flat 12 mm tapes, not
                         round cable; declared by a "tape_width" column
                         on the structure's segments and applied as a
                         drag-equivalent diameter (as_config
                         aerodynamic_bridle.tape_roll_model)
                         + apparent_wind.py: THE single source of
                         va(r) = va_free - omega x (r - r0), the relation that
                         puts a load at the right STATION on a rotating kite
                         (bridle segments, the KCU). The tether does NOT use
                         it: williams_tether rotates about the GROUND ANCHOR
                         with per-node wind, and the lumped closed form is an
                         integral, not a point evaluation
                         + trim_casadi.py: the quasi-steady trim as ONE CasADi
                         root-finding problem (trim states + circulations +
                         Williams length, exact Jacobian, numeric AIC frozen
                         per wake pass); 20-70x faster than the least-squares
                         trims, same result. panel_kernels.py = the section
                         force laws as xp kernels (numpy/casadi, one formula)
                         — see src/awetrim/aerodynamics/AGENTS.md
  aerostructural/    ✅  The coupling: shared interfaces (protocols, mapping,
                         convergence, forces, results, utils) plus one adapter
                         per Billow fidelity. The structural solver itself is
                         Billow, a separate package.
    coupled/         ✅  The coupled solve itself, backend-agnostic.
                         coupled_solver.py dispatches over wireframe / billow,
                         so a new backend is a branch there, not a copy;
                         awesio_structure.py is the ONE geometry reader
                         (load_structure -> Structure, an awesIO
                         structure document; Structure.resolved() is the
                         full model's solver arrays) both consume, and
                         aero2struc.py the ONE load transfer.
                         read_struc_geometry_yaml.py now only imports the
                         retired struc_geometry_FEM_full format.
                         aero2struc.chordwise_distribution offers
                         "moment_matched", which places each panel's load at
                         its own centre of pressure so the LOCAL pitching
                         moment is conserved (default stays "cp_file", one
                         fixed 0.291 c station for every panel, which
                         reproduces stored results)
    wireframe/       ✅  Adapter for Billow's WIREFRAME fidelity (cables,
                         tension-only lines, pulleys) + the PSM production
                         driver coupled_solver_qsm.py and the geometry reader
                         structural_geometry_io.py. Was pss/ until 2026-09-12
    billow/          ✅  Adapter for Billow's FULL fidelity: inflatable
                         Timoshenko tube beams and wrinkling CST membrane
                         canopy on top of the same cables and pulleys. Reads
                         the kite's structure.yml (awesIO; its tubes and
                         pressure). Converged on the LEI-V3
                         unactuated baseline
  kinematics/        ✅  course-frame kinematics, B-spline path patterns
                         (+ the slanted up-loop figure eight of the
                         single-period pumping cycle: slanted_eight_angles /
                         slanted_eight_landmarks (NumPy, Gerono lobes scaled to
                         the stated circles, s=0 at the low-lobe bottom),
                         make_slanted_eight_bspline_path_parameters (smallest
                         M under a metre of deviation; returns (dict, info)),
                         count_self_crossings / eight_crossing_s /
                         lobe_signed_areas (by="elevation" low/high or
                         by="azimuth" left/right) as topology + sense checks;
                         symmetrize_periodic_path: half a period of the
                         uniform periodic spline is an index shift by M/2, so
                         a mirrored path is a coefficient-pair condition)
  timeseries/        ✅  PhaseParameterized, ReeloutSimple, ReelinSimple, Cycle
                         (opti_phase sim_parameters.periodic_wrap: the seam
                         interval node N-1 -> node 0 of a one-period periodic
                         spline gets the same continuity / rate / AoA rows,
                         energy, time and regulariser term as the interior
                         ones -- the closed cycle without close_radial_cycle,
                         which it refuses to combine with; NLP byte-identical
                         when off. sim_parameters.mirror_symmetry (+
                         mirror_azimuth, default 0): half-period mirror rows
                         C_phi[k+M/2] = 2 az_c - C_phi[k], C_beta[k+M/2] =
                         C_beta[k] for optimized shape coefficients, and
                         node pairs i / i+N/2 with v_r, u_p equal and u_s
                         opposite; needs periodic_wrap, winch_mode
                         free_speed (the force law makes the v_r rows
                         degenerate), even M and N, and a fixed shape that
                         is already mirrored; off = NLP unchanged. PHYSICAL
                         only about the downwind meridian az = 0 (another
                         mirror_azimuth warns). Known LICQ degeneracy: each
                         active node bound is active at i and i+N/2
                         together, so with the mirror rows those rows are
                         dependent and their multipliers not unique; the
                         clean fix is elimination (declare only the first
                         half as variables) -- open follow-up.
                         sim_parameters.fix_depower_profile: per-node depower
                         held at its warm start (the full-cycle closing
                         stage). sim_parameters.depower_anchor_weight: the
                         soft alternative, w * mean(((l_dp - l_dp_warm) /
                         depower bound width)^2) in the objective
                         (objective_dict["depower_anchor"]); excludes the
                         hold (the closing stage of a --continue-from run:
                         its depower was optimal at another wind and in the
                         rated region only depowering sheds the extra
                         force). sim_parameters.parametric_speed_floor: the
                         anti-hesitation floor sigma' >= f sigma_ref without a
                         turn-radius constraint (the full-cycle seeds emit
                         0.2; a collapsed sigma' is a spline cusp that breaks
                         the node trim). The power objective's scale is
                         floored at 0.25 mean|P| of the warm start.
                         sim_parameters.reg_fraction: the control-smoothness
                         term (reg) weighted to that fraction of |objective|
                         at the NLP's initial point (phase.relative_reg_weight;
                         an explicit reg_weight wins). All
                         opt-in keys off = NLP unchanged)
  environment/       ✅  Wind (uniform / logarithmic / power_law / explog /
                         jet / tabulated). profile_laws.py is the ONLY place the
                         analytic formulas live (pure functions over an ``xp``
                         math namespace: numpy for fits/scripts, casadi inside
                         Wind); Wind stores one amplitude (speed_wind_ref at
                         height_ref, or speed_friction for log-based models) and
                         derives the other lazily. wind_factory.create_wind_model
                         builds fully numeric models; wind_profiles.py maps the
                         co-sim InflowConditions struct (laws 0-6, CUSTOM_* fits)
                         onto create_wind_model kwargs. profile_laws.air_density
                         is the density law rho0 exp(-(z + h_gnd)/8550)
                         (AtmosphericModels.jl calc_rho); Kite.rho stays the
                         constant unless Kite.air_density_model = {height_gnd,
                         scale_height?} is set, then lift/drag, KCU drag and the
                         lumped tether drag use it at z = r sin(beta)
                         (SystemModel.air_density) and the Williams tether
                         per node (air_density_at_height)
  server/            ✅  REST API for reelout trajectory optimization
                         (FastAPI, optional [server] extra; endpoints
                         /init /status /step /trajectory /reset; one
                         warm-started re-solve per /step for co-simulation
                         clients, e.g. an external kite simulator).
                         Co-sim structs: WinchParams {mode, k_v, f_min,
                         f_max, v_max|p_max, optimize_k_v, k_v_bounds}
                         (optimize_k_v -> slope_winch_ro becomes a design
                         variable, bracketed per request around the client's
                         k_v; replies echo the OPTIMIZED k_v and flag
                         optimized_parameters.k_v_at_bound), Trajectory,
                         DepowerParams {mode: fixed|optimize|profile, value},
                         InflowConditions {wind_speed @6 m, wind_direction
                         (compass, FROM), profile_law 0-6, alpha, z0,
                         heights/speeds, turbulence (ignored),
                         air_density_law constant|exponential, rho_zero
                         (default: the system file's rho), height_gnd},
                         InitParams, StepParams. Replies always echo the
                         depower the returned path assumes — it is not
                         flyable without it. Optional client-supplied
                         min_turn_radius [m] (init/step; echoed) maps to
                         sim_parameters.min_turn_radius, a dense geometric
                         curvature constraint in opti_phase; replies carry
                         metrics.turn_radius_min_m + a turn_radius column.
                         Optional pattern_limits {azimuth_max, elevation_min,
                         elevation_max, azimuth_amplitude_min} [deg]
                         (init/step; echoed) -> opti_limits_override C_phi/
                         C_beta (B-spline hull) + sim_parameters.
                         min_azimuth_amplitude (one smooth row in opti_phase).
                         Optional angle_of_attack_limits {min, max,
                         stall_margin} [deg] (init/step; echoed) ->
                         opti_limits_override angle_of_attack; stall_margin
                         = the ROM's angle_of_attack_stall minus it.
                         Launcher: examples/server/run_reelout_server.py
  flight_data/       ✅  reader of EKF-AWE output (load_flight -> FlightData); raw-log
                         processing and the EKF itself live in EKF-AWE
  plotting/          ✅  shared plotting helpers — see src/awetrim/plotting/AGENTS.md
  utils/             ✅  fitting, defaults, reference frames, control_metrics
                         (steering-reversal count / pairs outside a deadband,
                         seam pair counted on a periodic history)
  identification/    🟡  ROM aero-coefficient identification: the
                         aerostructural sweep dataset (aerostructural_dataset.py:
                         trims.csv / polars.csv of run_identification_sweep.py,
                         dimensional, vectors as _x/_y/_z in the trim frame;
                         coefficient_tables -> CL/CD samples and the
                         theta_b / phi_a trim samples of paper App. D), tidy
                         dataset (aero_dataset.py, AS + EKF sources, shared schema),
                         BIC forward-stepwise polynomial fit with k-fold CV
                         (aero_polynomial.py → rom_config "coeffs"), control
                         conventions (controls.py), rigid_body_axes.py
                         (body axes anchored to the wing's CENTRE PANEL,
                         aircraft FRD sense; never inertia eigenvectors).
                         Regressors: alpha, u_s, u_p, v_a; targets CL/CD/phi_a.
                         (aero LUT guide is outdated and needs revising)