Private API

@with_kw mutable struct SerializedModel{...}

A type-stable container for the compiled and serialized components of a SymbolicAWEModel.

This struct holds the products of the ModelingToolkit.jl compilation process, now organized into nested attribute structs (ProbWithAttributes, etc.). This simplifies the structure and improves serialization robustness.

• set_hash::Vector{UInt8}

• sys_struct_hash::Vector{UInt8}

• full_sys::Union{Nothing, ModelingToolkitBase.System}: Unsimplified system of the mtk model Default: nothing

• defaults::AbstractVector: Default: Pair{Num, Any}[]

• guesses::AbstractVector: Default: Pair{Num, Any}[]

• inputs::Union{Symbolics.Arr, Vector{Symbolics.Num}}: Symbolic representation of the control inputs. Default: Num[]

• outputs::Union{Symbolics.Arr, Vector{Symbolics.Num}}: Outputs of the linearization and control function. Default: Num[]

• prob::Union{Nothing, SymbolicAWEModels.ProbWithAttributes}: Container for the ODE problem and its getters/setters. Default: nothing

• lin_prob::Union{Nothing, SymbolicAWEModels.LinProbWithAttributes}: Container for the linearization problem and its components. Default: nothing

• control_functions::Union{Nothing, SymbolicAWEModels.ControlFuncWithAttributes}: Container for the control functions. Default: nothing

const SimFloat = Float64

This type is used for all real variables, used in the Simulation. Possible alternatives: Float32, Double64, Dual Other types than Float64 or Float32 do require support of Julia types by the solver.

const KVec3 = MVector{3, SimFloat}

Basic 3-dimensional vector, stack allocated, mutable.

const SVec3 = SVector{3, SimFloat}

Basic 3-dimensional vector, stack allocated, immutable.

create_vsm_wing(set::Settings, vsm_set::VortexStepMethod.VSMSettings; prn=true, sort_sections=true)

Create a VortexStepMethod.Wing geometry object from the settings provided.

This function checks for .obj and .dat files in the model directory. If found, it uses VortexStepMethod.ObjWing(obj_path, dat_path) to load the wing. Otherwise, it falls back to loading from aero_geometry.yaml.

build_vsm_engine(set, vsm_set, dynamics_type; point_to_vsm_point=nothing,
                 wing_segments=nothing, aero_scale_chord=0.0, aero_z_offset=0.0)

Build a VSMEngine: create the VortexStepMethod vsm_wing/vsm_aero/ vsm_solver and size the linearization state vectors. Aero-state sizes are placeholders for RIGID_DYNAMICS (using n_unrefined_sections as the twistsurface-count proxy) and resized by SystemStructure once twistsurfaces are resolved.

copy!(sys1::SystemStructure, sys2::SystemStructure)

Copy the dynamic state from one SystemStructure (sys1) to another (sys2).

This function is designed to transfer the state (positions, velocities, etc.) between two system models, which can have different levels of fidelity. For example, it can copy the state from a detailed multi-segment tether model (sys1) to a simplified single-segment model (sys2).

The function handles several cases:

• If sys1 and sys2 have the same structure, it performs a direct copy of all point states.
• If sys2 is a simplified (1-segment per tether) version of sys1, it copies the positions and velocities of the tether endpoints.
• It also copies the state of wings, twist_surfaces, winches, and pulleys where applicable.

reinit!(transforms::AbstractVector{Transform}, sys_struct::SystemStructure;
        update_vel=true)

Apply transforms to all components in a SystemStructure.

Expects pos_w to already be set (via copy_cad_to_world! and optionally apply_tether_init_stretched_lens! from reinit!(sys_struct, set; ...)). Applies: translate (from pos_w) → azimuth/elevation → heading.

reinit!(sys_struct::SystemStructure, set::Settings; kwargs...)

Re-initialize a SystemStructure from a Settings object.

This function resets various component states (e.g., winch lengths, twist_surface twists, pulley positions) to their initial values as defined in the Settings object. It is typically called before starting a new simulation run.

Pulley lengths are initialized proportionally based on current segment lengths: pulley.len = segment1.len / (segment1.len+segment2.len) * pulley.sum_len

Keyword Arguments

• ignore_l0::Bool=false: If true, recalculate segment rest lengths from current positions
• remake_vsm::Bool=false: If true, recreate VSM wing, aerodynamics, and solver from settings. This is useful after modifying aero_geometry.yaml or other VSM-related configuration files. For PARTICLEDYNAMICS wings, also rebuilds the `pointtovsmpoint` mapping.
• apply_transforms::Bool=true: If false, skip applying spatial transforms (translate, rotate, heading) during reinitialization.
• apply_tether_lengths::Bool=true: If false, skip scaling point positions to match tether.init_stretched_len.
• prn::Bool=true: If true, print info messages (e.g. when several root tethers are placed to their mean stretched length).

reinit!(sam, prob, solver; kwargs...) -> (ODEIntegrator, Bool)

Reset the ODE integrator from new initial conditions without rebuilding the symbolic model. See init! for adaptive, reset_integrator, lin_vsm, and vsm_min_wind.

reposition!(transforms::AbstractVector{Transform},
            sys_struct::SystemStructure)

Update the system's spatial orientation based on its current position, preserving velocities.

Unlike reinit!, uses current world positions (pos_w) as the starting point (no reset from CAD coordinates, no tether length scaling). Heading uses the tangential sphere frame, consistent with reinit!.

update_sys_struct!(s::SymbolicAWEModel, sys_struct::SystemStructure, integ=s.integrator)

Updates the high-level SystemStructure from the low-level integrator state vector.

This function reads the raw state vector from the ODE integrator and uses the generated getter functions to populate the human-readable fields in the SystemStructure. This synchronization step is crucial for making the simulation results accessible.

get_set_hash(set::Settings; fields)

Calculates a SHA1 hash for structural fields in the Settings object. This is used to check if a cached compiled model is still valid.

Structural Fields (affect symbolic equations):

• :segments: Number of tether segments (affects state vector size)
• :model: Kite model name (affects geometry)
• :foil_file: Airfoil data file (affects VSM setup)
• :physical_model: Model type (ram, simpleram, 4attach_ram)
• :quasi_static: Whether points are quasi-static (affects equations)
• :winch_model: Winch dynamics model (affects winch equations)

Runtime Fields (don't affect compilation, excluded from hash):

• :profile_law: Wind profile law (evaluated at runtime via symbolic function)
• :wind_vec, :elevation: Initial conditions
• Other runtime parameters

get_sys_struct_hash(sys_struct::SystemStructure)

Calculates a SHA1 hash for the topology and structure of a SystemStructure. This is used to check if a cached compiled model is still valid.

Includes all structural properties that affect the symbolic equations:

• Point connectivity and types (STATIC, DYNAMIC, QUASI_STATIC, WING)
• Segment connectivity
• TwistSurface structure and types (FIXED, TWIST)
• Pulley constraints and types
• Tether topology
• Winch configuration
• Wing topology, connectivity, aerodynamic model type (RIGIDDYNAMICS vs PARTICLEDYNAMICS), and aero mode
• Transform hierarchy

Excludes runtime-configurable properties like masses, lengths, stiffnesses.

calc_angle_of_attack(va_wing_b)

Calculate the angle of attack [rad] from the apparent wind vector va_wing_b in the body frame.

calc_heading(sys::SystemStructure)

Calculate heading angles for all wings using the tangential sphere frame method. Returns a vector of heading angles, one per wing.

calc_heading(R_b_to_w, wing_pos)

Calculate heading angle using the tangential sphere frame.

Projects the body x-axis onto the tangent plane of the tether sphere at wing_pos. Heading is measured from the elevation direction (xt, away from zenith) toward the azimuthal direction (yt). Heading = 0 when the kite nose points toward the ground station.

calc_R_t_to_w(wing_pos)

Calculate the rotation matrix from the local tether frame (_t) to the world frame (_w).

The tether frame is a local spherical coordinate system:

• z-axis: Aligned with the tether (radial direction).
• y-axis: Azimuthal direction, parallel to the XY plane.
• x-axis: Elevation direction, tangent to the sphere (y × z).

calc_R_v_to_w(wing_pos, e_x)

Calculate the rotation matrix from the view frame (_v) to the world frame (_w).

The view frame is defined with its z-axis pointing from the origin to the wing, and its x-axis aligned with the wing's x-axis projected onto the view plane.

cad_to_body_frame(wing::Wing, pos)

Transform a position from the CAD frame to the wing's body frame.

calc_pos(wing::Wing, gamma, frac)

Calculate a position on the kite based on spanwise (gamma) and chordwise (frac) parameters.

calc_winch_force(sys, winch_vel, winch_acc, set_values)

Calculate the tensile force on each winch tether from its motion and motor torque, using the default-component motor dynamics inverted for the force connector.

Reads friction from the live winch struct (populated each step from the component output), so the formula matches whatever the component reported even if the component overrides friction.

quaternion_to_rotation_matrix(q)

Convert a quaternion q (scalar-first format [w, x, y, z]) to a 3x3 rotation matrix.

rotation_matrix_to_quaternion(R)

Convert a 3x3 rotation matrix R to a quaternion (scalar-first format [w, x, y, z]). This implementation is based on the method that avoids division by zero.

rotate_v_around_k(v, k, θ)

Rotate vector v around axis k by angle θ using Rodrigues' rotation formula.

smooth_norm(v, eps=1e-12)

Differentiable norm: sqrt(sum(abs2, v) + eps^2).

smooth_normalize(vec)

Differentiable normalization: vec / smooth_norm(vec).

apply_heading(vec, R_t_to_w, curr_R_t_to_w, heading)

Apply a heading rotation to a vector.

get_rot_pos(transform::Transform, wings, points)

Get the world position of the rotating object (wing or point).

get_base_pos(transform, transforms, wings, points)

Get (base_pos, curr_base_pos) for a transform.

For chained transforms (base_transform): returns the parent's current world position and CAD position, so T = base_pos - curr_base_pos shifts child points by the same displacement the parent transform applied.

For direct transforms (base_pos + base_point): returns the user-specified position and the base point's current position.

calc_aoa(s::SymbolicAWEModel)

Angle of attack [rad] of the first wing, dispatched on its aero mode (calc_aoa(::AbstractAeroModel, wing)). NaN if the mode defines no AoA.

calc_aoa(mode::AbstractAeroModel, wing) -> SimFloat

Angle of attack [rad] for wing under aero mode. Defaults to NaN (undefined); VSM modes read the mid-span geometric AoA (wrapped to [-π, π]) and AeroPlate derives it from the body-frame apparent wind.

create_sys!(s::SymbolicAWEModel, system::SystemStructure; prn=true)

Create the full ModelingToolkit.ODESystem for the AWE model.

This is the main top-level function that orchestrates the generation of the entire set of differential-algebraic equations (DAEs). It calls specialized sub-functions to build the equations for each part of the system (forces, wing dynamics, scalar kinematics, linearized aerodynamics) and assembles them into a single System.

Arguments

• s::SymbolicAWEModel: The main model object to be populated with the system.
• system::SystemStructure: The physical structure definition.
• prn::Bool=true: If true, print progress information during system creation.

Returns

• set_values: The symbolic variable representing the control inputs (winch torques).

scalar_eqs!(s, eqs, psys; kwargs...)

Generate equations for derived scalar kinematic quantities useful for control and analysis.

This includes elevation, azimuth, heading, course, angle of attack, and their time derivatives, as well as apparent wind calculations.

Arguments

• s::SymbolicAWEModel: The main model object.
• eqs, psys: Accumulating vectors and symbolic parameter.
• kwargs...: Symbolic variables for the system's state.

Returns

• eqs: The updated list of system equations.

wing_eqs!(s, eqs, psys, defaults; kwargs...)

Generate the differential equations for the wing's rigid body dynamics.

For RIGID_DYNAMICS wings:

• ODE state: com_w, com_vel, Q_p_to_w, ω_p (principal frame)
• Euler rotation equations in principal frame (diagonal I)
• Newton's 2nd law for COM translation
• Body frame output (R_b_to_w, wing_pos, ω_b) computed algebraically via R_b_to_w = R_p_to_w * R_b_to_p (constant)

For PARTICLE_DYNAMICS wings:

• No rigid body dynamics (handled by DYNAMIC points)
• R_b_to_w from structural ref points
• Principal frame variables set to zero/aliases

aero_eqs!(s, eqs, guesses, psys; kwargs...)
    -> (eqs, guesses, aero_subsystems)

Instantiate and wire each wing's aero component. Returns the list of component subsystems to attach to the parent System.

point_eqs!(s, eqs, defaults, guesses, points, segments, twist_surfaces, wings, psys;
           R_b_to_w, wing_vel, wind_vec_gnd, twist_angle,
           pos, vel, acc, point_force, point_mass, spring_force_vec, drag_force, l0,
           spring_sum_force, point_drag_force, total_drag,
           disturb_force, tether_r, chord_b, fixed_pos, normal, pos_b,
           fix_point_sphere, fix_static, body_frame_damping, world_frame_damping,
           va_point_b, va_point_w, wind_at_point, height,
           aero_force_point_b,
           twist_surface_y_airf, tether_wing_force, tether_wing_moment)

Generate equations for all point types (STATIC, DYNAMIC, QUASI_STATIC, WING).

Arguments

• s::SymbolicAWEModel: The main model object (for atmospheric model).
• eqs, defaults, guesses: Accumulating vectors for the MTK system.
• points, segments, twist_surfaces, wings: System components.
• psys: Symbolic parameter representing the system structure.
• R_b_to_w: Symbolic rotation matrix (body to world).
• wing_vel: Symbolic wing center of mass velocity.
• wind_vec_gnd: Symbolic ground-level wind vector.
• twist_angle: Symbolic twist_surface twist angle.
• pos, vel, acc: Pre-declared point state variables.
• point_force, point_mass: Pre-declared point force and mass variables.
• spring_force_vec, drag_force, l0: Pre-declared segment force variables.
• spring_sum_force: Pre-declared accumulated spring/drag forces variable.
• Other variables: Various point-specific symbolic variables.
• tether_wing_force, tether_wing_moment: Mutable arrays to accumulate forces/moments.

Returns

• Tuple (eqs, defaults, guesses) with updated equation vectors. Note: tether_wing_force and tether_wing_moment are modified in-place.

segment_eqs!(s, eqs, guesses, points, segments, pulleys, tethers, wings, psys;
             pos, vel, wind_vec_gnd, spring_force_vec, drag_force, l0,
             pulley_len, tether_len)

Generate equations for segment spring-damper forces and aerodynamic drag.

Arguments

• s::SymbolicAWEModel: The main model object (for atmospheric model).
• eqs, guesses: Accumulating vectors for the MTK system.
• points, segments, pulleys, tethers, wings: System components.
• psys: Symbolic parameter representing the system structure.
• pos, vel: Symbolic point state variables.
• wind_vec_gnd: Symbolic ground-level wind vector.
• spring_force_vec, drag_force, l0: Pre-declared segment force variables.
• pulley_len, tether_len: Symbolic state variables for pulley and tether lengths.

Returns

• Tuple (eqs, guesses, len, spring_force) with updated equation vectors and the segment length and spring force variables for use by other components.

refresh_aero!(sam::SymbolicAWEModel, prob::ProbWithAttributes,
              integ=sam.integrator; vsm_min_wind=0.5)

Refresh each wing's aerodynamic state, dispatching on the wing's aero mode (refresh_rigid_aero! / refresh_particle_aero!). Runs on the low-frequency VSM-update schedule (vsm_interval), not the compiled RHS.

RIGID_DYNAMICS VSM modes: compute wind-axis coefficients (CL, CD, CS, CM, cm) at the operating point, plus the ForwardDiff Jacobian over [α, β, ω₁, ω₂, ω₃, θ_twist…] (AeroLinearized) or the frozen forces (AeroDirect).

PARTICLE_DYNAMICS VSM modes: full nonlinear VSM solve with per-point force distribution. Non-VSM modes (AeroNone/AeroPlate) are no-ops.

jacobian(f::Function, x::AbstractVector, ϵ::AbstractVector) -> Matrix

Numerically compute the Jacobian of a vector-valued function f at point x.

This function uses a simple forward finite difference method to approximate the partial derivatives of f with respect to each component of x.

Arguments

• f::Function: The function to differentiate (y = f(x)).
• x::AbstractVector: The point at which to evaluate the Jacobian.
• ϵ::AbstractVector: A vector of perturbation sizes for each component of x.

Returns

• Matrix: The Jacobian matrix J, where J[i, j] = ∂f[i] / ∂x[j].

load_serialized_model!(sam, model_path; remake=false, reload=false)

Load a serialized model from disk if it is valid.

A model is considered valid if its settings and system structure hashes match the current ones in the SymbolicAWEModel object (sam).

Arguments

• sam::SymbolicAWEModel: The main model object.
• model_path::String: The path to the serialized model file.
• remake::Bool: If true, forces the model to be considered invalid, triggering a rebuild.
• reload::Bool: If true, forces reloading from disk even if the model is already in memory.

Returns

• true if a valid model was successfully loaded into sam.serialized_model, false otherwise.

maybe_create_lin_prob!(sam, outputs; ...)

Create and cache the LinearizationProblem if it does not exist or if the outputs have changed.

Arguments

• sam::SymbolicAWEModel: The main model object.
• outputs: A vector of output variables for the linearization.
• create_lin_prob::Bool: Flag to enable/disable creation.
• outputs_changed::Bool: Flag indicating if the output vector has changed.
• prn::Bool: Flag to enable/disable printing of progress messages.

Returns

• true if a new problem was created, false otherwise.

maybe_create_control_functions!(sam, outputs; ...)

Create and cache the control functions if they do not exist or if the outputs have changed.

Arguments

• sam::SymbolicAWEModel: The main model object.
• outputs: A vector of output variables for the control functions.
• create_control_func::Bool: Flag to enable/disable creation.
• outputs_changed::Bool: Flag indicating if the output vector has changed.
• prn::Bool: Flag to enable/disable printing of progress messages.

Returns

• true if new functions were created, false otherwise.

maybe_create_prob!(sam; create_prob=true, prn=true)

Create and cache the ODEProblem if it does not already exist.

This function compiles the full system, creates the ODEProblem, and generates the necessary getter/setter functions.

Arguments

• sam::SymbolicAWEModel: The main model object.
• create_prob::Bool: A flag to enable or disable the creation of the problem.
• prn::Bool: A flag to enable or disable printing of progress messages.

Returns

• true if a new problem was created, false otherwise.

has_custom_component(sys_struct)

Return true when the system has a non-default winch model or a wing using a custom aero model, in which case the compiled model cannot be reused from cache and must be rebuilt.

generate_control_funcs(model, inputs, outputs)

Generate in-place and out-of-place control functions from a ModelingToolkit system.

This function wraps ModelingToolkit.generate_control_function and ModelingToolkit.build_explicit_observed_function to create the necessary functions for simulation and analysis.

Arguments

• model: The full ODESystem.
• inputs: A vector of input variables.
• outputs: A vector of output variables.

Returns

• A NamedTuple containing the generated functions (f_oop, f_ip, h_oop, h_ip), system dimensions (nu, nx, ny), and symbolic variables (dvs, psym, io_sys).

generate_lin_getters(sys)

Generate setter functions for the parameters of a linearized system.

Arguments

• sys: The linearized ModelingToolkit system.

Returns

• A NamedTuple containing setter functions for the winch set-points (set_set_values), and the system structure parameters (set_sys).

generate_prob_getters(sys_struct, sys)

Generate getter and setter functions for the state variables of the full system model.

These functions provide a convenient way to access and modify the state and parameters of the compiled ODESystem (sys).

Arguments

• sys_struct::SystemStructure: The structure defining the system topology.
• sys::ODESystem: The compiled ModelingToolkit system.

Returns

• A NamedTuple containing various getter and setter functions for different parts of the system state.

@with_kw struct LinProbWithAttributes{SetLinSetValues, SetLinSys, SetLinSet, LinOut}

A container for the general-purpose linearization problem and the resulting full linearized model (A,B,C,D matrices).

• prob::Any: Linearization problem of the mtk model.

• set_set_values::Any

• set_sys::Any

@with_kw struct ProbWithAttributes{...}

A container for the main Ordinary Differential Equation (ODE) problem and its associated getter and setter functions for the full, nonlinear physical state.

@with_kw struct ControlFuncWithAttributes{FIP, FOOP, HIP, HOOP, DVS, PSYM}

A container for callable control functions and their symbolic representations, generated from the full system model.

• f_ip::Any: In-place dynamics function f(dx, x, u, p, t).

• f_oop::Any: Out-of-place dynamics function dx = f(x, u, p, t).

• h_ip::Any: In-place observation function h(y, x, u, p, t).

• h_oop::Any: Out-of-place observation function y = h(x, u, p, t).

• nu::Int64: Number of inputs (u).

• nx::Int64: Number of states (x).

• ny::Int64: Number of outputs (y).

• dvs::Any: The symbolic state vector.

• psym::Any: The symbolic parameter vector.

• io_sys::ModelingToolkitBase.System: The generated input-output system.

get_model_name(set::Settings, sys_struct::SystemStructure; precompile=false)

Constructs a unique filename for the serialized model based on its configuration. The filename includes the SymbolicAWEModels version, Julia version, physical model, wing type, dynamics type, and component counts to ensure that the correct cached model is loaded.

calc_height(s::SymbolicAWEModel)

Returns the height (z-position) [m] of the wing.

pos(s::SymbolicAWEModel)

Returns a vector of the position vectors [m] for each point in the system.

spring_forces(s::SymbolicAWEModel)

Returns the spring force [N] for each tether segment.

calc_spring_props(sam, tether_sam; prn=false) -> (Vector, Vector, Matrix, Float64)

Calculate the equivalent stiffness and damping, and return the step response data.

This function orchestrates the process by performing a step response test on the tether_sam model and then analyzing the resulting tether length data.

Arguments

• sam::SymbolicAWEModel: The reference model, used for its physical properties.
• tether_sam::SymbolicAWEModel: A copy of the model to perform the step test on.

Keywords

• prn::Bool=false: If true, enables printing of intermediate results.

Returns

• Tuple{Vector{Float64}, Vector{Float64}, Matrix{Float64}, Float64}: A tuple containing:
  1. unit_stiffness [N]
  2. unit_damping [Ns]
  3. tether_lens (the step response data)
  4. dt (the simulation time step)

calc_spring_props(sam, tether_lens, F_step; p=5, prn=false) -> (Vector, Vector)

Calculate spring constant k and damping coefficient c from a step response.

This function analyzes the time series of tether lengths (tether_lens) resulting from a step force (F_step) to estimate the parameters of an equivalent second-order mass-spring-damper system.

Arguments

• sam::SymbolicAWEModel: The model from which to take physical parameters (mass).
• tether_lens::Matrix{Float64}: A matrix of tether length time series data.
• F_step::Float64: The magnitude of the applied step force.

Keywords

• p::Int=5: The percentage band used to determine the settling time.
• prn::Bool=false: If true, enables printing of detailed calculations.

Returns

• Tuple{Vector{Float64}, Vector{Float64}}: A tuple containing two vectors:
  1. k_values (spring constants [N/m])
  2. c_values (damping coefficients [Ns/m])

in_percent_band(x, steady, delta_x, i, p) -> Bool

Helper function to check if a time series has settled within a percentage band.

It checks if all values of the time series x from index i to the end are within a tolerance band defined by p percent of the total change delta_x.

step(sam, steps, F_step, F_0; abs_tol, consecutive_steps_needed, prn) -> Matrix

Apply a step force to a model and simulate its dynamic response.

This function records the length of each tether over a specified number of simulation steps. It includes an early exit condition if the system's state settles.

Arguments

• sam::SymbolicAWEModel: The model to be simulated.
• steps::Int: The total number of simulation steps.
• F_step::Float64: The magnitude of the step force to apply.
• F_0::Vector{KVec3}: The initial force vector for each tether attachment point.

Keywords

• abs_tol::Float64=1e-6: Absolute tolerance for the settling check.
• consecutive_steps_needed::Int=10: Number of consecutive steps required to be within tolerance to be considered settled.
• prn::Bool=false: If true, enables printing of status messages.

Returns

• Matrix{Float64}: A matrix where each row corresponds to a tether and each column to a time step, containing the tether lengths.

create_model_archive(source_dir, archive_path)

Finds all model*.bin files in the source_dir, copies them to a temporary directory, and compresses that directory into a .tar.gz archive at the specified archive_path.

filecmp(path1::AbstractString, path2::AbstractString) -> Bool

Compare two files byte-by-byte to check if they are identical.

extract_model_archive(archive_path, dest_dir)

Safely decompress a .tar.gz file by first extracting to a temporary directory and then copying the contents to the final destination.

Arguments

• archive_path::String: The path to the .tar.gz file to be extracted.
• dest_dir::String: The path to the target directory.

copy_bin()

Copy all example scripts to the folder "bin" (it will be created if it doesn't exist).

copy_examples()

Copy all example scripts to the folder "examples" (it will be created if it doesn't exist).

copy_data()

Copy all data scripts to the folder "data" (it will be created if it doesn't exist).

copy_dir(src_dir, dst_dir)

Copies all files from src_dir to dst_dir. Overwrites existing files if force=true. Creates dst_dir if it does not exist.

get_example_packages()

Get the list of packages from examples/Project.toml, excluding SymbolicAWEModels itself. This ensures init_module installs the correct dependencies for running examples.

make_lin_sys_state(y::AbstractVector, sam::SymbolicAWEModel, t::Real)

Construct a SysState for logging linear state-space simulation output y (ordered as sam.outputs).

SAM_FIELDS

Tuple of field names that are direct fields of SymbolicAWEModel (as opposed to fields delegated to the nested serialized_model). Used by getproperty and setproperty! to dispatch field access correctly.

Access item by numeric index.

Access item by symbolic name.

Base.getindex(x::ModelingToolkit.Symbolics.Arr, idxs::Vector{Int64})

Extend Base.getindex to allow indexing a symbolic array with a vector of integer indices, which is not natively supported by ModelingToolkit.

Base.getproperty(pa::ProbWithAttributes, sym::Symbol)

Overloads getproperty to provide convenient access to the simplified system (sys) contained within the ODE problem's function definition.

Base.setproperty!(sam::SymbolicAWEModel, sym::Symbol, val)

Overloads setproperty! to allow direct setting of fields within the nested serialized_model. This allows you to change properties of the compiled model as if they were fields of the SymbolicAWEModel itself.

get_field_or_nothing(::Type{T}, row::NamedTuple,
                     field::Symbol) where T

Convert field to type T if present, otherwise return nothing.

Examples

get_field_or_nothing(Int64, row, :idx)  # -> Int64 or nothing
get_field_or_nothing(Tuple{Int64,Int64}, row, :pair)
    # -> (Int64, Int64) or nothing

convert_to_type(::Type{T}, value) where T

Convert value to type T. Handles special cases like Tuples.

resolve_references(row::NamedTuple, property_tables::Dict{String, Dict{String, NamedTuple}})

Resolve string references in a row by looking them up in property tables. If a field value is a String, check if it exists as a key in any property table. If found, merge those properties into the current row (current row takes precedence).

calculate_derived_properties!(props::Dict{Symbol, Any})

Calculate derived properties like unit_stiffness and unit_damping from material properties. Modifies props in-place.

extract_args(row, args_spec, mappings)

Extract positional constructor arguments from a YAML row.

For each name in args_spec, this helper first checks for a mapping in mappings, then falls back to row[arg_name]. Throws an error if a required argument is missing.

call_yaml_constructor(Constructor, row::NamedTuple,
    args_spec, kwargs_spec; mappings=Dict())

Generic YAML-to-constructor caller. Extracts positional args and kwargs from YAML row and calls constructor.

Arguments

• Constructor: Constructor function to call
• row::NamedTuple: Parsed YAML row
• args_spec::Vector{Symbol}: Names for positional args
• kwargs_spec::Vector{Symbol}: Names for kwargs

Keyword Arguments

• mappings::Dict{Symbol, Function}: Mapping functions that take the row and return the arg value

Example

row = (idx=1, x=0.0, y=0.0, z=0.0, type="STATIC")
point = call_yaml_constructor(Point, row,
    [:idx, :pos_cad, :type],  # positional args
    [:extra_mass, :wing_idx];       # kwargs
    mappings=Dict(
        :pos_cad => r -> [Float64(r.x),
            Float64(r.y), Float64(r.z)],
        :type => r -> parse_dynamics_type(
            String(r.type))
    ))

parse_tether_init(row, tether_name)
    -> (stretched_length, tether_force, stretch_frac)

Read init_stretched_length, init_tether_force and init_stretch_frac from a tether YAML row (each nothing if absent). Errors if the deprecated init_unstretched_length field is present — the unstretched rest length is now derived from the placed stretched length with init_tether_force or init_stretch_frac.

segment_cad_length(segment::Segment, points)

Compute segment length from endpoint pos_cad positions.

segment_world_length(segment::Segment, points)

Compute segment length from endpoint pos_w positions.

tether_ordered_point_idxs(tether, segments)

Point indices along the tether, ordered from start_point_idx through each segment's far endpoint to the end point.

tether_anchor_free(tether, boundary)

Return (anchor_idx, free_idx) for a root tether: the endpoint in boundary (STATIC/winch points) is the anchor, the other is free. Returns (nothing, nothing) if neither endpoint is on a boundary; errors if both are.

rigid_point_siblings(points, wings)

Map each WING-type point index of a RIGID_DYNAMICS wing to the set of all such points sharing that wing. These points move as one rigid body without inter-point segments, so the set captures their connectivity for downstream traversal.

tether_downstream_idxs(tether, segments, boundary, from_idx,
                       anchor_idx, rigid_siblings)

Breadth-first set of point indices reachable from from_idx (the tether's free end) through segments outside this tether and through rigid_siblings, stopping at boundary points. These are the points that must translate with the free end when the tether is repositioned. Errors if traversal reaches anchor_idx (a loop back to the anchor).

twist_surface_tethers_by_overlap(specified, reach)

Cluster the specified tethers with a union-find over reach (point indices each tether touches): tethers whose reaches intersect share structure and land in the same cluster. Returns a vector of tether vectors, one per cluster.

tether_unit_stiffness(tether, segments)

Return the common per-unit-length stiffness [N] of the tether's segments. Errors if the segments are not uniform, since the spring inversion in apply_tether_init_forces! assumes a single stiffnesys_state.

apply_cluster_init_stretched_len!(cluster, points, segments,
                                  downstream, boundary; prn=true)

Reposition one cluster of root tethers so each sits at its init_stretched_len standoff. Each tether contributes the displacement that would move its free end onto the target length along the anchor→free direction; the free end and everything downstream of it are translated by the mean of those displacements, then interior points are redistributed proportionally along each tether. For a multi-tether cluster, logs an @info when prn.

apply_tether_init_stretched_lens!(sys_struct::SystemStructure; prn=true)

Scale pos_w so each tether with an explicit init_stretched_len sits at that standoff. Call after copy_cad_to_world!. Rest length is derived separately by apply_tether_init_forces!.

Only tethers with one endpoint on a boundary (STATIC or winch point) are placed; that endpoint is the fixed anchor (start or end). Scaling runs from the anchor toward the free end, translating everything downstream of it. A tether with neither endpoint anchored is an error. Roots feeding one structure form a cluster, placed by their mean displacement (length and direction).

Errors if a downstream segment connects back to the anchor.

init_unstretched_len(tether, segments) -> SimFloat

Derived initial unstretched (rest) length from the tether's current (placed) stretched length stretched = Σ segment lengths:

• init_stretch_frac set: len = stretch_frac · stretched (< 1 pre-stretch, 1 neutral, > 1 slack).
• otherwise from init_tether_force (default 0): len = stretched · (1 − force / unit_stiffness) (zero-velocity, tension branch). Force 0 gives len = stretched (no tension).

Errors if both init_stretch_frac and init_tether_force are set, if stretch_frac ≤ 0, if force < 0, if force ≥ unit_stiffness, or if the segments have non-uniform unit_stiffness.

apply_tether_init_forces!(sys_struct::SystemStructure)

Set every tether's len to its init_unstretched_len. Must be called after segment world lengths are current.

assign_indices_and_resolve!(components, name_dicts)

Assign indices to all components based on their position in the vectors, and resolve all references to indices.

resolve_ref(ref::NameRef, name_dict::Dict{Symbol, Int64}, component_type::String) -> Int64

Resolve a reference (name or index) to an index using the name dictionary. If ref is an integer, returns it directly. If ref is a symbol, looks up in dictionary.

resolve_ref_spec(spec, name_dict, component_type) -> Union{Int64, Vector{Int64}, Nothing}

Resolve a reference point specification (single ref or vector of refs) to indices.

validate_sys_struct(sys_struct::SystemStructure)

Validate a SystemStructure for common configuration errors.

This function checks for issues that can cause initialization failures or numerical problems during simulation. It emits warnings for suspicious configurations and throws assertions for definite errors.

Validations Performed

Point Validations

• NaN extra_mass (error)
• Negative extra_mass (warning)
• Non-positive total_mass for DYNAMIC points (error) - checked before NaN position
• NaN position (error) - often caused by zero mass

Wing Validations

• Non-positive mass (error) - checked before NaN position
• Zero or near-zero principal inertia components on RIGID_DYNAMICS wings (error/warning)
• NaN inertia values (error)
• Empty twistsurface list for RIGIDDYNAMICS wings (warning)
• NaN position (error) - often caused by zero mass/inertia

Winch Validations

• Zero or negative inertia_total (error)
• Very small inertia_total (warning)
• NaN inertia_total (error)
• Non-positive drum_radius (error)
• Non-positive gear_ratio (error)

Segment Validations

• Unusual diameter outside (0, 1) m range (warning)
• Non-positive rest length l0 (error)
• Zero or negative stiffness (warning)
• Negative damping (warning)

Pulley Validations

• Zero total length constraint (error)

TwistSurface Validations

• Inconsistent momentfrac across twistsurfaces (error)

build_name_dict(items::Vector) -> Dict{Symbol, Int64}

Build a name→index dictionary from a vector of items with optional name fields. Items with name=nothing are skipped. Integer names are converted to Symbols.

setup_wing_frame!(wing, points; prn=true)

Compute a wing's body frame (R_b_to_c, pos_cad) and, for RIGID_DYNAMICS, its COM offset and principal inertia, from the WING points and ref points. This is dynamics/geometry only — independent of the aero mode, which does its own mode-specific setup afterwards in setup_aero!.

auto_create_twist_surfaces!(wing, points, twist_surfaces; prn=false)

Auto-create one DYNAMIC TwistSurface per LE/TE structural section for a section-coupled RIGIDDYNAMICS VSM wing that has none, append them to `twistsurfaces, setwing.twistsurfaceidxs`, and resize the wing's aero arrays.

compute_twist_surface_geometry!(wing, twist_surfaces, points)

For each of wing's twist surfaces with an unset chord, derive its leading-edge position, chord vector, and spanwise airfoil axis from the nearest VSM refined section (body frame). Used for auto-created twist surfaces.

setup_particle_point_mapping!(wing, points, twist_surfaces)

For a VSM PARTICLE_DYNAMICS wing, build the structural↔panel point mapping and LE/TE wing_segments if not already set. Errors if the required body-frame z_ref_points/y_ref_points are missing.

identify_wing_segments(wing_points; twist_surfaces=nothing, wing_twist_surface_idxs=nothing)

Identify wing segments (LE/TE pairs) from WING-type points.

When twist_surfaces and wing_twist_surface_idxs are provided, uses twistsurface `pointidxsto determine LE (pointidxs[1]) and TE (pointidxs[end]`) for each section. Falls back to a consecutive-pair heuristic (sorted by point index) when twist_surfaces are unavailable.

In both paths an x-coordinate check swaps LE/TE if needed (LE has smaller pos_cad[1]).

Arguments

• wing_points::AbstractVector{Point}: WING-type points for a wing.

Keyword Arguments

• twist_surfaces::Union{Nothing, AbstractVector{TwistSurface}}: All twistsurfaces in the system (indexed by `wingtwistsurfaceidxs`).
• wing_twist_surface_idxs::Union{Nothing, AbstractVector{<:Integer}}: Indices into twist_surfaces belonging to this wing.

Returns

• Vector{Tuple{Int64, Int64}}: (lepointidx, tepointidx) pairs.

match_aero_sections_to_structure!(wing, points; twist_surfaces)

Reconcile a wing's aerodynamic sections with its structural geometry.

RIGIDDYNAMICS wings own their aero panel geometry (mesh- or YAML-defined) and keep it; only the twistsurface→section mapping (wing.wing_segments) is recorded. PARTICLEDYNAMICS wings deform with their structural points, so each unrefined section is rebuilt onto its structural LE/TE pair: a 1:1 copy when counts match, otherwise `usepriorpolarand existingrefinedsections` are required to preserve polars.

Keyword Arguments

• twist_surfaces::AbstractVector{TwistSurface}: TwistSurfaces used for LE/TE identification via identify_wing_segments.

compute_spatial_twist_surface_mapping!(the_wing, twist_surfaces, points)

Partition the wing's unrefined VSM sections among its twistsurfaces by spatial proximity: each unrefined section is assigned to the single closest twistsurface (by distance between section centre and twist_surface centre, both in body frame).

When n_twist_surfaces == n_unrefined this is the same 1:1 mapping as before. When n_twist_surfaces < n_unrefined a twistsurface may own several adjacent sections; its single twist DOF then drives all of them as a rigid unit. The case `ntwistsurfaces > nunrefined` is rejected — a twist DOF without a section to drive would be undefined.

copy_cad_to_world!(points, wings; update_vel=true)

Copy CAD geometry to world frame for ALL points and wings. Sets pos_w = pos_cad (and Q_b_to_w to initial CAD orientation for wings). Must be called before reinit!(transforms, ...).

adjust_vsm_panels_to_origin!(vsm_wing, origin_offset)

Adjust VSM panel positions when body frame origin changes.

When RIGIDDYNAMICS wings are loaded from YAML, the panel positions in aerogeometry.yaml are specified in an absolute body frame. However, the body frame origin is adjusted to the mean position of all WING points. This function updates all panel positions to be relative to the new origin by subtracting the offset.

Arguments

• vsm_wing: VortexStepMethod.Wing with sections to adjust
• origin_offset: Vector [x, y, z] to subtract from panel positions

apply_aero_z_offset!(vsm_wing, aero_z_offset)

Apply z-axis offset to VSM panel positions in body frame.

For RIGID_DYNAMICS wings, this shifts the aerodynamic center of pressure in the positive z-direction (body frame) to adjust the moment arm. This is applied AFTER the COM adjustment.

Arguments

• vsm_wing: VortexStepMethod.Wing with sections to adjust
• aero_z_offset: Distance to shift panels in +z direction [m]

calc_particle_dynamics_wing_frame(points, z_ref_points, y_ref_points, origin)

Calculate Rbto_w rotation matrix and origin position from structural point positions.

Algorithm

1. Weighted ref point positions
2. Z-axis (normal): zp1 → zp2
3. X-axis (chord): Y_temp × Z
4. Y-axis (span): Z × X (orthogonal, right-handed)
5. Origin from weighted origin ref points

calc_inertia_y_rotation(I_tensor)

Find the Y-axis rotation that diagonalizes the XZ block of the inertia tensor (zeros out I[1,3] and I[3,1]).

Returns (I_diag, Ry) where I_diag = Ry * I_tensor * Ry' and Ry is a rotation about the Y axis by angle θ = atan(2·I₁₃, I₁₁ − I₃₃) / 2.

rotate_vsm_sections!(vsm_wing, R)

Rotate all VSM section LE/TE points by rotation matrix R.

Used during initialization to transform sections from CAD frame to body frame. After the first step, refresh_aero!() updates positions from pos_b (already in body frame).

expand_auto_tethers!(points, segments, tethers, set)

For Route 2 tethers (auto-generation), create intermediate DYNAMIC points and segments. Must be called before assign_indices_and_resolve!.

Detects Route 2 tethers by checking start_point_ref !== nothing and segment_refs names not yet present in segments.

WeightedRefPoints

Weighted combination of reference points for wing frame definition. Supports single points, equal-weight averaging, and arbitrary weight combinations.

Fields

• refs: Unresolved names/indices (filled at construction)
• ids: Resolved point indices (filled by resolve!)
• weights: Normalized weights (sum to 1.0)

resolve!(ref_pt::WeightedRefPoints, name_dict, type)

Resolve symbolic refs to integer indices, filling ref_pt.ids. No-op if refs is empty (already resolved).

Warn and normalize if weights don't sum to 1.

SegmentType `POWER_LINE` `STEERING_LINE` `BRIDLE`

names(nc::NamedCollection)

Return a vector of all symbolic names in order of their indices. Names are nothing for unnamed items.

get_idx(nc::NamedCollection, name::Symbol)

Get the numeric index for a given symbolic name.

get_name(nc::NamedCollection, idx::Integer)

Get the symbolic name for a given numeric index, or nothing if unnamed.

Get all symbolic names in the collection.

Get all values (same as iterating).

Check if a symbolic name exists in the collection.

Set item by numeric index.

Set item by symbolic name.

tether_eqs!(eqs, tethers; len, spring_force)

Generate equations for tether stretched length and average spring force.

Arguments

• eqs: Accumulating equation vector.
• tethers: Collection of Tether objects.
• len: Symbolic segment length variable.
• spring_force: Symbolic segment spring force variable.

Returns

• Updated eqs vector with tether equations.

pulley_eqs!(eqs, defaults, guesses, pulleys, segments, psys;
            spring_force, pulley_len, pulley_vel)

Generate equations for pulley dynamics (rope distribution over pulleys).

Arguments

• eqs, defaults, guesses: Accumulating vectors for the MTK system.
• pulleys: Collection of Pulley objects.
• segments: Collection of Segment objects (for mass calculation).
• psys: Symbolic parameter representing the system structure.
• spring_force: Symbolic segment spring force variable.
• pulley_len, pulley_vel: Symbolic pulley state variables.

Returns

• Tuple (eqs, defaults, guesses) with updated equation vectors.

winch_eqs!(eqs, defaults, winches, tethers, segments, points,
           sys_struct, psys;
           spring_force_vec, set_values, tether_len,
           winch_vel, winch_acc, winch_force_vec, winch_friction)

Generate equations for winch motor dynamics and per-tether length state, and return the list of ODESystem subsystems to attach to the parent system.

For each winch:

1. Sum spring force vectors of the segments meeting the winch point (sign-aware via segment point_idxs) → winch_force_vec.
2. Instantiate the user's winch component via winch.model(...).
3. Validate the connector contract with validate_winch_component.
4. Bind connectors to the parent variables (including subsys.len ~ mean(tether_len[tether_idx] for tether_idx in winch.tether_idxs)) and integrate D(winch_vel) = ifelse(brake > 0.5, 0, winch_acc). When winch.speed_controlled is true, winch_acc is forced to 0 (ignoring subsys.acc) so velocity is prescribed via winch.vel.

For each tether:

• With winch: D(tether_len) = ifelse(brake > 0.5, 0, winch_vel).
• Without winch: D(tether_len) = 0.

twist_surface_eqs!(eqs, defaults, guesses, twist_surfaces, wings, psys;
           R_b_to_w, fix_wing, twist_angle, twist_ω, twist_surface_aero_moment,
           point_force, tether_wing_moment, twist_surface_y_airf, twist_surface_chord, twist_surface_le_pos)

Generate equations for deformable wing twist_surface twist dynamics.

Arguments

• eqs, defaults, guesses: Accumulating vectors for the MTK system.
• twist_surfaces: Collection of TwistSurface objects (deformable wing sections).
• wings: Collection of Wing objects.
• psys: Symbolic parameter representing the system structure.
• R_b_to_w: Symbolic rotation matrix (body to world).
• fix_wing: Symbolic boolean for fixing wing dynamics.
• twist_angle, twist_ω: Symbolic twist state variables.
• twist_surface_aero_moment: Symbolic aerodynamic moment on twist_surfaces.
• point_force: Symbolic point force variable.
• tether_wing_moment: Accumulated tether moments on wings (for validation).
• twist_surface_y_airf, twist_surface_chord, twist_surface_le_pos: Symbolic twist_surface geometry variables.

Returns

• Tuple (eqs, defaults, guesses) with updated equation vectors.

validate_twist_surface_modes(twist_surfaces, wings)

Check that each twist_surface's twist mode is coherent with its owning wing's dynamics and its point count. Errors loudly on an inconsistent combination:

• DYNAMIC/QUASI_STATIC twist is an added rigid-body deformation DOF and needs a bridle couple, so it requires a RIGID_DYNAMICS wing and ≥2 points.
• A 1-point twist_surface has no bridle couple to oppose a twist moment, so its only coherent twist is prescribed → must be FIXED.
• FIXED twist on a PARTICLE_DYNAMICS wing cannot move free particles, so it is only coherent for a single point.

load_plate_wing(row, idx, data, set, wing_type, aero_mode,
                yaml_to_ref, yaml_parse_ref_points,
                yaml_parse_origin, twist_surfaces)

Load a flat-plate wing from a YAML wing row + surfaces block. Each surface becomes a 1-point FIXED TwistSurface appended to twist_surfaces; the wing references them by name. CL/CD interpolations come from Settings polar data.

plate_corners(twist_surface, point_pos_w, R_b_to_w) -> NTuple{4, Vector}

World-frame corners of a flat-plate section's display quad. The section's structural point sits at quarter chord; the quad is a square of side sqrt(area) spanned by the twisted chord direction and y_airf, so the quad area matches the section's area.

vsm_engine(mode::AbstractAeroModel) -> Union{Nothing, VSMEngine}

The mode's VSMEngine (VSM geometry + linearization state), or nothing for modes without one. After construction every AbstractVSMAero carries an engine (require_vsm_engine enforces this in setup_aero!); nothing only occurs for non-VSM modes and bare pre-construction markers. Used for the wing's VSM property forwarding and the VSM-settings loading; per-mode behaviour goes through the dispatch hooks instead.

has_vsm_engine(mode::AbstractAeroModel) -> Bool

true if vsm_engine(mode) returns an engine. Derived, not a dispatch point — implement vsm_engine instead.

require_vsm_engine(mode, wing) -> VSMEngine

Return the mode's VSMEngine, erroring with construction advice when it is missing (a bare AeroDirect()/AeroLinearized() marker attached to a wing that was not built via VSMWing). Called once, in setup_aero!; after construction every AbstractVSMAero is guaranteed to carry an engine.

couples_to_sections(mode::AbstractAeroModel) -> Bool

true if the mode needs per-section twist surfaces (auto-creation and aero-section matching). VSM modes (AbstractVSMAero) do.

provides_aero_override(mode::AbstractAeroModel) -> Bool

true if the mode supplies frozen body-frame force/moment overrides read by the compiled RHS (the stored-force path of AeroDirect).

stores_point_force(mode::AbstractAeroModel) -> Bool

true if a WING point's aero_force_b is meaningful for this mode. AeroNone returns false (it produces no force).

aero_mode_tag(mode::AbstractAeroModel) -> String

Short identifier for the mode in the compiled-model cache filename. Required: the AbstractAeroModel fallback errors, so every aero mode must declare its own tag (no silent default that could collide two distinct modes on one cache file). Built-ins: "lin", "dir", "none", "plate".

calc_side_slip(wing) -> SimFloat

Side-slip angle [rad] from the body-frame apparent wind. Pure geometry — the same formula for every aero mode, so it does not dispatch.

validate_aero_component(subsys, wing)

Check the built aero subsys exposes the connectors the wiring layer needs for the wing's dynamics_type; error naming the missing connector otherwise.

validate_aero_structure(mode, wing, points; prn=false)

Check structural invariants the mode's compiled equations rely on (run at build). Default no-op; VSM PARTICLE_DYNAMICS wings verify the structural↔panel point mapping exists, covers every WING point, and matches 2 × n_sections points.

remake_aero!(mode, wing, set, vsm_set, points, twist_surfaces)

Rebuild the mode's aero engine from set/vsm_set (the remake_vsm path in reinit!, used after editing settings). Default no-op; VSM modes recreate the VSM wing/aero/solver, re-transform sections to the body frame, re-match aero sections to structure, and rebuild the twist-surface / point mappings.

setup_aero!(mode, wing, points, twist_surfaces; prn=false)

Construction-time aero setup for wing, dispatched on its aero mode (default no-op). VSM modes transform the VSM panels into the body frame and, for section-coupled wings, auto-create twist surfaces, match aero sections to structure, and build the twist-surface / structural↔panel mappings. A custom mode adds a method to participate in construction without editing the SystemStructure constructor. Runs after setup_wing_frame! (which sets the body frame).

resize_aero_state!(mode, wing)

Resize the mode's per-wing aero state after wing.twist_surface_idxs is resolved (name resolution can change the twist-surface count the initial sizing estimated from n_unrefined). Default no-op; VSM modes resize aero_y/aero_x/aero_jac for RIGID_DYNAMICS wings.

init_aero_state!(mode, wing, va_b_init)

Initialize the mode's aero state from the initial body-frame apparent wind va_b_init (runs in update_sys_struct!, before the first refresh). Default no-op; VSM modes write the operating-point angles α, β into aero_y.

normalized_inertia(mode::AbstractAeroModel, wing, points)
    -> (com_cad, inertia)

Normalized (per-unit-mass) inertia of the wing body about its COM in the CAD frame, with inertia in [m²] — multiply by the wing's mass for the physical tensor [kg·m²]. inertia is nothing when there is no mass to normalize by. The default normalizes the WING-point point-mass inertia (normalized_point_inertia); VSM modes with an ObjWing mesh return the per-unit-mass mesh tensor as-is (its COM is -T_cad_body) and fall back to the point masses otherwise.

normalized_point_inertia(wing, points) -> (com_cad, inertia)

Per-unit-mass inertia of the wing's WING points treated as point masses (extra_mass), normalized by their total mass. Exact under the construction invariant wing.mass == sum of WING-point masses (the constructor distributes set.mass onto the points). With zero total mass, com_cad is the unweighted centroid and inertia is nothing.

n_aero_log_points(mode, wing) -> Int

Number of extra SysState log slots the mode contributes for wing (visualization geometry such as panel corners). Default 0; VSM modes log 4 corners per panel. Must match what write_aero_log_points! writes.

n_aero_log_points(::AeroPlate, wing) -> Int

4 quad corners per flat-plate section (plate_corners).

write_aero_log_points!(mode, wing, sys_struct, sys_state, point_idx,
                       zoom) -> Int

Write the mode's log points (world frame, scaled by zoom) into sys_state.X/Y/Z starting after point_idx; return the last index written. Default writes nothing; VSM modes write the panel corners, AeroPlate writes each section's display quad.

write_aero_log_points!(::AeroPlate, wing, sys_struct, sys_state,
                       point_idx, zoom) -> Int

Log each flat-plate section's display quad (plate_corners).

read_aero_log_points!(mode, wing, sys_struct, sys_state, point_idx) -> Int

Inverse of write_aero_log_points!: restore the mode's state from the logged points starting after point_idx; return the last index consumed (the slots must be skipped even when unused). Default consumes nothing; VSM PARTICLE_DYNAMICS modes read the panel corners back (rigid wings recompute panels from twist instead and only skip their slots).

read_aero_log_points!(::AeroPlate, wing, sys_struct, sys_state,
                      point_idx) -> Int

Skip the quad-corner slots: plate corners are derived from the restored structural point positions, so nothing is read back.

restore_aero_twist!(mode, wing, twist_surfaces)

Re-apply the (already restored) twist-surface angles to the mode's geometry when loading a SysState log frame. Default no-op; VSM RIGID_DYNAMICS modes deform the unrefined sections and reinit the panels.

plot_wing_aero!(ax, sys, wing, mode::AbstractAeroModel;
                use_observables=false, geometry_obs=nothing)

Render wing's aero geometry into ax, dispatched on its aero mode: VSM modes plot their panels via VortexStepMethod's recipe, flat-plate modes draw their section quads in the same style (red mesh, black borders). The default draws nothing — add a method for a custom mode to render its own geometry. With use_observables, the plot re-reads the live structure on every geometry_obs trigger (live plots and replay). Returns the plot object, or nothing when nothing was drawn. Defined in the Makie extension.

update_wing_aero_plot!(wing, mode::AbstractAeroModel)

Per-frame update of wing's aero plot, dispatched on its aero mode. Default no-op; VSM modes push the current pose into the panel-mesh observables. Modes drawn through the geometry observable (flat-plate quads) need no update here. Defined in the Makie extension.

load_wing(mode::AbstractAeroModel, row, idx, data, set, wing_type, vsm_set,
          yaml_to_ref, yaml_parse_ref_points, yaml_parse_origin, twist_surfaces)

Build a wing from a parsed YAML row, dispatched on its aero mode. The default (VSM-backed modes) builds a VSMWing; AeroPlate builds a flat-plate wing via load_plate_wing. Add a method to load a wing for a custom aero mode.

refresh_rigid_aero!(mode, wing, am, twist_surfaces; vsm_min_wind=0.5)

Refresh a RIGID_DYNAMICS wing's aero state, dispatched on its aero mode:

• AeroNone / any non-VSM mode → no-op (fallback).
• AeroLinearized → compute the baseline coefficients (rigid_aero_baseline!) and the ForwardDiff Jacobian d(coeffs)/d(inputs) into wing.aero_jac.
• AeroDirect → compute the baseline coefficients and apply the frozen body-frame force/moment; below vsm_min_wind everything is zeroed.

refresh_rigid_aero!(::AeroDirect, wing, am, twist_surfaces; vsm_min_wind=0.5)

Direct rigid-wing refresh. Computes the baseline coefficients and applies the resulting frozen body-frame force/moment (apply_direct_forces!), which the RHS holds constant until the next refresh. Below vsm_min_wind the coefficients, Jacobian, force, moment, and per-twist-surface moments are zeroed.

refresh_rigid_aero!(::AeroLinearized, wing, am, twist_surfaces; vsm_min_wind=0.5)

Linearized rigid-wing refresh. Computes the baseline wind-axis coefficients at the operating point (rigid_aero_baseline!), then the ForwardDiff Jacobian d(coeffs)/d(inputs) and stores it in wing.aero_jac. The compiled RHS uses that Jacobian to reconstruct forces via a first-order Taylor expansion about the operating point.

refresh_particle_aero!(mode, wing, points, va_point_b_vals; vsm_min_wind=0.5)

Refresh a PARTICLE_DYNAMICS wing's aero state, dispatched on its aero mode:

• AeroNone / any non-VSM mode → no-op (fallback).
• AeroDirect → full nonlinear VSM solve with per-section apparent wind, then distribute panel forces onto the wing's structural points (distribute_panel_forces_to_points!); below vsm_min_wind the point forces are zeroed.
• AeroLinearized → unsupported (errors).

refresh_particle_aero!(::AeroDirect, wing, points, va_point_b_vals; vsm_min_wind=0.5)

Direct particle-wing refresh. Runs the full nonlinear VSM solve using each section's apparent wind (averaged from its LE/TE point velocities in va_point_b_vals), then distributes the resulting panel forces onto the wing's structural points (distribute_panel_forces_to_points!). Below vsm_min_wind the point forces are zeroed.

refresh_particle_aero!(::AeroLinearized, wing, points, va_point_b_vals; vsm_min_wind=0.5)

Unsupported: AeroLinearized is not implemented for PARTICLE_DYNAMICS wings and errors. Use AeroDirect (per-point nonlinear VSM) for particle wings.

count_aero_log_points(wings) -> Int

Total extra SysState log slots contributed by the wings' aero modes (n_aero_log_points): 4 per VSM panel for VSM modes, 4 per section quad for flat-plate wings, 0 by default.

build_point_to_vsm_point_mapping(wing_points::AbstractVector{Point}, wing::Wing)

Build 1:1 mapping from structural WING points to VSM wing section points (LE/TE) using closest-point distance.

For each VSM section point (LE/TE), finds the closest structural point. Distances are computed in body frame: structural pos_cad is transformed via wing.R_b_to_c' and wing.pos_cad before being compared against section LE/TE points (which already live in body frame after match_aero_sections_to_structure!).

Constraint

Requires: length(wing_points) == 2 * length(wing.vsm_wing.unrefined_sections)

update_vsm_wing_from_structure!(wing::Wing, points::AbstractVector{Point})

Update VSM section points (LE/TE) directly from structural point positions using 1:1 mapping.

This creates two-way coupling: structural deformation → VSM sections → aero forces.

Algorithm

Uses direct 1:1 correspondence between structural points and VSM section points:

1. For each structural WING point:
   • Calculate current position in body frame: posb = Rbtow' * (pos_w - origin)
   • Find corresponding VSM section point (LE or TE) via wing.pointtovsm_point
   • Set VSM section point directly: section.LEpoint = posb (or TE_point)

Notes

• Section points are stored in body frame coordinates
• wing.R_b_to_w and wing.pos_w are updated each timestep from structural geometry (symbolic equations)
• To get world coordinates: world_pos = wing.R_b_to_w * section.LE_point + wing.pos_w

Arguments

• wing::Wing: Wing with PARTICLE_DYNAMICS type
• points::AbstractVector{Point}: All structural points (will filter for WING type)

distribute_panel_forces_to_points!(wing::Wing, points::AbstractVector{Point})

Distribute VSM forces to structural points using refined panel forces.

After VSM solve, each refined panel force/moment is split into corner-node forces (moment-preserving about the chosen reference) and then aggregated to the structural LE/TE points of the parent section (1:1 mapping).

Algorithm

1. Initialize all WING point aero_forces to zero
2. Build inverse mapping from section → LE/TE structural point indices
3. For each refined panel of this wing:
   • Get panel force/moment from solver solution (body frame)
   • Map panel to its parent section using refined_panel_mapping
   • Split to LE/TE forces with compute_aerostruc_loads
   • Accumulate forces at the corresponding structural points

Arguments

• wing::Wing: Wing with PARTICLE_DYNAMICS type and solved VSM state
• points::AbstractVector{Point}: All structural points (will filter for WING type)

rigid_aero_baseline!(wing, twist_surfaces; vsm_min_wind=0.5)

Compute the operating point and baseline wind-axis coefficients for one wing: writes wing.aero_y / wing.aero_x and updates twist_surfaces[gidx].aero_moment. Returns the context (va_mag, section counts, moment_frac, shadow_ref, y0) the mode-specific reduction (refresh_rigid_aero!) needs for the Jacobian.

Apply direct forces from wind-axis coefficients.

vsm_aero_coeffs(wing, y, va_mag, n_unrefined, n_twist_surfaces,
                 twist_surface_idxs, twist_surfaces, moment_frac, shadow_ref;
                 gamma_init=nothing) -> Vector

Run one VSM solve at operating-point input y = [α, β, ω₁, ω₂, ω₃, θ_twist…] and return the wind-axis coefficient vector [CL, CD, CS, CM₁, CM₂, CM₃, cm_twist…]. ForwardDiff.Dual-aware via vsm_solve_objects: for a Dual eltype it solves on a cached dual shadow of the VSM solver, so the same routine yields the Jacobian under AD.

vsm_solve_objects(wing, ::Type{T}, shadow_ref) -> (body_aero, solver, wing)

The VSM solve objects vsm_aero_coeffs runs on, selected by the input eltype T. A value pass (Float64) uses the wing's real objects. A ForwardDiff pass feeds Dual numbers through the solve to get the Jacobian, but the real objects' buffers are Float64 and can't hold Duals — so for a Dual eltype we solve on a Dual-typed "shadow" of the solver/aero. The shadow is expensive, so it is built lazily and cached in shadow_ref, keyed by the Dual eltype (rebuilt if it changes); use_gamma_prev warm-starts each perturbed solve from the previous circulation.

NaN/Inf-guarded solve!. Checks both Dual value and partials. On non-finite or non-converged result, zero gamma and return false.

finite_full(x) -> Bool

true if x is finite. For a ForwardDiff.Dual it also checks every partial, so a NaN/Inf derivative is caught — used by safe_vsm_solve! to reject a bad VSM solve during the Jacobian pass, not just the value pass.

solve_heading_rotation(R_b_to_w, target_heading, wing_pos)

Calculate the rotation angle around the radial axis needed to achieve target_heading.

With the tangential sphere heading, rotating around the radial axis by θ simply shifts the heading by θ, so the solution is target_heading - current_heading.

get_ref_position_from_points(points, ref_pt; field=:pos_w)

Weighted position from structural points. field selects which point coordinate to read (:pos_w or :pos_cad).

sym_calc_R_t_to_w(wing_pos)

Symbolic version of calc_R_t_to_w that uses explicit element access to avoid slice scalarization issues.

wrap_to_pi(angle)

Wrap angle to [-π, π] range.

apply_azimuth_elevation!(transform, wings, points, base_pos; update_vel=false)

Apply the azimuth/elevation rotation of a single transform to all components in it. Returns (curr_R_t_to_w, R_t_to_w) for use in the heading step.

apply_heading!(transform, wings, points,
                curr_R_t_to_w, R_t_to_w, base_pos)

Apply heading rotation to all components in a single transform. Rotates around the radial axis through base_pos (not the origin). Uses wing.R_b_to_w for the no-ref-points orientation source. After copy_cad_to_world!, this equals wing.R_b_to_c (for reinit!), or the current world orientation (for reposition!).

finalize_transforms!(wings, points)

Finalize transforms: update PARTICLE_DYNAMICS wing frames from structural point positions, then compute principal frame ODE state.

init_principal_frame!(wings, points)

Compute principal frame ODE state from body frame. Must be called after body frame (pos_w, R_b_to_w, vel_w, ω_b) is fully initialized.

Sets: com_w, Q_p_to_w, com_vel, ω_p (derived from body frame), and pos_b for RIGID_DYNAMICS wing points (body frame, relative to COM).

init_body_frame_from_ref_points!(wing, points; prn=true)

Initialize wing body frame (Rbtoc, poscad) from z/y reference points. Shared by VSMWing PARTICLE_DYNAMICS and PlateWing.

update_segment_forces!(sys_struct::SystemStructure)

Calculate and update spring forces for all segments in-place.

This function computes the spring-damper forces for each segment using the same formulas as in generate_system.jl. It updates the len and force fields of each segment in the SystemStructure.

The spring-damper force follows Hooke's law with damping:

\[F = k(l - l_0) - c\dot{l}\]

where:

• k = unit_stiffness / l (tension) or k = compression_frac * unit_stiffness / l (compression)
• l is current length, l_0 is unstretched length
• c = unit_damping / l is damping coefficient
• \dot{l} = (v₁ - v₂) ⋅ û is extension rate

Arguments

• sys_struct::SystemStructure: The system structure containing points and segments.

Returns

• nothing: Modifies segment.len and segment.force in-place.

Example

update_segment_forces!(sam.sys_struct)
for segment in sam.sys_struct.segments
    println("Segment $(segment.idx): force = $(segment.force) N")
end

get_rot_pos_cad(transform::Transform, wings, points)

Get the CAD-frame position of the rotating object (wing or point). Used by get_base_pos to compute the translation offset for chained transforms.

KiteUtils.Logger(sam::SymbolicAWEModel, steps::Int)

Constructs a Logger from a SymbolicAWEModel with the correct number of points.

This convenience constructor automatically calculates the total number of points including VSM panel corners (4 corners per panel) and creates a Logger with the appropriate size.

Arguments

• sam::SymbolicAWEModel: The AWE model to create a logger for.
• steps::Int: The number of time steps to allocate for logging.

Returns

• Logger: A new logger with size for all points including panel corners.

Example

logger = Logger(sam, 1000)  # Instead of Logger(length(sam.sys_struct.points), 1000)