DynamicsType `DYNAMIC` `QUASI_STATIC` `WING` `STATIC` `FIXED`

Enumeration for the dynamic model governing a point's motion or a twist_surface's twist.

Elements

• DYNAMIC: The point is a dynamic point mass, moving according to Newton's second law.
• QUASI_STATIC: The point's acceleration is constrained to zero, representing a force equilibrium.
• WING: The point is rigidly attached to a wing body and moves with it.
• STATIC: The point's position is fixed in the world frame.
• FIXED: TwistSurface twist is a prescribed control input (no differential state, no algebraic equilibrium). Read live via the registered twist getter.

WingType `RIGID_DYNAMICS` `PARTICLE_DYNAMICS`

Enumeration for the aerodynamic model type of a wing.

Elements

• RIGID_DYNAMICS: Wing uses quaternion-based rigid body dynamics with twist twist_surfaces. Aerodynamic forces/moments are applied to the wing center of mass.
• PARTICLE_DYNAMICS: Wing uses refined per-panel forces directly applied to structural points. VSM panel forces are lumped to WING-type points with no rigid body constraint.

AbstractAeroModel

Supertype for a wing's aerodynamic model. The concrete subtype selects, by dispatch, the aero_component builder that emits the wing's aero equations. Built-in subtypes: AeroNone, AeroDirect, AeroLinearized, AeroPlate. Subtype it and add an aero_component method to plug in custom aerodynamics; see the VSM coupling documentation for a worked example with a live-updating field.

AeroNone()

No aerodynamic forces (returns zeros). For debugging rigid body dynamics or a wing with no aero coupling. Needs no VSM geometry and carries no state.

abstract type AbstractVSMAero <: AbstractAeroModel

Aero modes backed by a VSMEngine (stored in the engine field). VSM operations dispatch on this supertype; the engine's fields (vsm_wing, aero_x, …) are forwarded from the mode. Built-in subtypes: AeroDirect and AeroLinearized.

AeroDirect()

Stored forces from the nonlinear VSM solve, piecewise-constant between updates. Carries a VSMEngine; the no-arg form is the engine-less marker filled in during wing construction.

AeroLinearized()

First-order Taylor expansion using the Jacobian from VSM linearization (RIGID_DYNAMICS only). Carries a VSMEngine; the no-arg form is the engine-less marker filled in during wing construction.

AeroPlate(calc_cl, calc_cd; drag_corr=1.0)

Flat-plate CL/CD lookup aerodynamics. Carries the shared polar lookups (calc_cl/calc_cd: α_deg → coefficient) and drag correction used by all of a wing's flat-plate (1-point FIXED) TwistSurfaces. One polar set per wing.

aero_component(mode::AbstractAeroModel, sys_struct, wing_idx; name) -> System

Build the aero subsystem for sys_struct.wings[wing_idx], selected by dispatch on the wing's aero model. Returns a System exposing the connectors fixed by the wing's dynamics_type (see above). Add a method on a custom AbstractAeroModel subtype to plug in your own aerodynamics.

is_builtin_aero(mode::AbstractAeroModel) -> Bool

true for the package's built-in aero models. Custom models return false, which forces a model rebuild (the compiled cache cannot be reused for user-supplied equations). Each built-in mode sets this in its aero_modes/ file.

aero_hash_id(mode::AbstractAeroModel) -> Tuple

Structural fields of mode that change the generated equations and therefore must enter the model-cache key. Return only fields that alter the equation structure, never runtime-mutable values (those are read live via registered getters). Defaults to an empty tuple.

mutable struct SymbolicAWEModel <: AbstractKiteModel

The main state container for a kite power system model, built using ModelingToolkit.jl.

This struct holds the complete state of the simulation, including the physical structure (SystemStructure), the compiled model (SerializedModel), the atmospheric model, and the ODE integrator.

Users typically interact with this model through high-level functions like init! and next_step! rather than accessing its fields directly.

Type Parameters

• S: Scalar type, typically SimFloat.
• V: Vector type, typically KVec3.
• P: Number of tether points in the system.

• sys_struct::SystemStructure: Reference to the point mass system with points, segments, pulleys and tethers

• serialized_model::SymbolicAWEModels.SerializedModel: Container for the compiled and serialized model components

• integrator::Union{Nothing, OrdinaryDiffEqCore.ODEIntegrator}: The ODE integrator for the full nonlinear model Default: nothing

• t_0::Float64: Relative start time of the current time interval Default: 0.0

• iter::Int64: Number of next_step! calls Default: 0

• t_vsm::Float64: Time spent in the VSM linearization step Default: zero(SimFloat)

• t_step::Float64: Time spent in the ODE integration step Default: zero(SimFloat)

SymbolicAWEModel(set::Settings, sys_struct::SystemStructure; kwargs...)

Constructs a SymbolicAWEModel from an existing SystemStructure.

This is the primary inner constructor. It takes a SystemStructure that defines the physical layout of the kite system and prepares it for symbolic model generation.

Arguments

• set::Settings: Configuration parameters.
• sys_struct::SystemStructure: The physical system definition.
• kwargs...: Further keyword arguments passed to the SymbolicAWEModel constructor.

Returns

• SymbolicAWEModel: A model ready for symbolic equation generation via init!.

struct SystemStructure

A discrete mass-spring-damper representation of a kite system.

This struct holds all components of the physical model, including points, segments, winches, and wings, forming a complete description of the kite system's structure.

Components

• Point: Point masses.
• TwistSurface: Collections of points for wing deformation.
• Segment: Spring-damper elements.
• Pulley: Elements that redistribute line lengths.
• Tether: TwistSurfaces of segments controlled by a winch.
• Winch: Ground-based winches.
• Wing: Rigid wing bodies.
• Transform: Spatial transformations for initial positioning.

SystemStructure(name, set; points, twist_surfaces, segments, pulleys, tethers, winches, wings, transforms)

Constructs a SystemStructure object representing a complete kite system.

Physical Models

• "ram": A model with 4 deformable wing twist_surfaces and a complex pulley bridle system.
• "simple_ram": A model with 4 deformable wing twist_surfaces and direct bridle connections.

Arguments

• name::String: Model identifier ("ram", "simple_ram", or a custom name).
• set::Settings: Configuration parameters from KiteUtils.jl.

Keyword Arguments

• points, twist_surfaces, segments, etc.: Vectors of the system components.
• prn::Bool=true: If true, print info messages about auto-generated components.

Returns

• SystemStructure: A complete system ready for building a SymbolicAWEModel.

mutable struct Point

A point mass, representing a node in the mass-spring system.

• idx::Int64: Index in the points vector (assigned by SystemStructure).

• name::Union{Nothing, Int64, Symbol}

• transform_idx::Int64: Resolved transform index (filled by SystemStructure).

• wing_idx::Int64: Resolved wing index (filled by SystemStructure).

• transform_ref::Union{Int64, Symbol}

• wing_ref::Union{Int64, Symbol}

• pos_cad::StaticArraysCore.MVector{3, Float64}

• pos_b::StaticArraysCore.MVector{3, Float64}

• pos_w::StaticArraysCore.MVector{3, Float64}

• vel_w::StaticArraysCore.MVector{3, Float64}

• disturb::StaticArraysCore.MVector{3, Float64}

• force::StaticArraysCore.MVector{3, Float64}

• aero_force_b::StaticArraysCore.MVector{3, Float64}

• drag_force::StaticArraysCore.MVector{3, Float64}

• va_b::StaticArraysCore.MVector{3, Float64}

• type::DynamicsType

• extra_mass::Float64: User-provided mass [kg].

• total_mass::Float64: Total mass [kg]: extra_mass + segment contributions (computed during simulation).

• body_frame_damping::StaticArraysCore.MVector{3, Float64}: Per-axis damping in body frame [N·s/m].

• world_frame_damping::StaticArraysCore.MVector{3, Float64}: Per-axis damping in world frame [N·s/m].

• area::Float64: Cross-sectional area for drag [m²].

• drag_coeff::Float64: Drag coefficient [-].

• fix_sphere::Bool: If true, constrain point to a sphere.

• fix_static::Bool: If true, dynamically freeze point position.

Point(name, pos_cad, type; wing=1, transform=1, ...)

Constructs a Point object, which can be of four different DynamicsTypes:

• STATIC: The point does not move. $\ddot{\mathbf{r}} = \mathbf{0}$
• DYNAMIC: The point moves according to Newton's second law. $\ddot{\mathbf{r}} = \mathbf{F}/m$
• QUASI_STATIC: The acceleration is constrained to be zero by solving a nonlinear problem. $\mathbf{F}/m = \mathbf{0}$
• WING: The point has a static position in the rigid body wing frame. $\mathbf{r}_w = \mathbf{r}_{wing} + \mathbf{R}_{b\rightarrow w} \mathbf{r}_b$

Arguments

• name::Union{Int, Symbol}: Name/identifier for the point (e.g., :kcu, :le_1, or 1 for legacy).
• pos_cad::KVec3: Position of the point in the CAD frame.
• type::DynamicsType: Dynamics type of the point (STATIC, DYNAMIC, etc.).

Keyword Arguments

• wing::Union{Int, Symbol}=1: Reference to the wing (name or index).
• transform::Union{Int, Symbol}=1: Reference to the transform (name or index).
• vel_w::KVec3=zeros(KVec3): Initial velocity of the point in world frame.
• extra_mass::Float64=0.0: User-provided mass of the point [kg].
• body_frame_damping::Union{Float64,KVec3}=zeros(KVec3): Per-axis damping for body frame.
• world_frame_damping::Union{Float64,KVec3}=zeros(KVec3): Per-axis damping for world frame.
• fix_sphere::Bool=false: If true, constrains the point to a sphere.
• fix_static::Bool=false: If true, dynamically freezes the point.

Returns

• Point: A new Point object. The idx field is assigned later by SystemStructure.

mutable struct TwistSurface

A set of bridle lines that share the same twist angle and trailing edge angle.

• idx::Int64: Index in the twist_surfaces vector (assigned by SystemStructure).

• name::Union{Nothing, Int64, Symbol}

• point_idxs::Vector{Int64}: Resolved point indices (filled by SystemStructure).

• point_refs::Vector{Union{Int64, Symbol}}

• le_pos::StaticArraysCore.MVector{3, Float64}: Leading edge position in body frame [m] (from closest VSM panel).

• chord::StaticArraysCore.MVector{3, Float64}: Chord vector in body frame [m] (from closest VSM panel).

• y_airf::StaticArraysCore.MVector{3, Float64}: Spanwise vector in local panel frame (from closest VSM panel).

• type::DynamicsType

• moment_frac::Float64: Chordwise rotation point fraction (0=LE, 1=TE).

• damping::Float64: Damping coefficient for twist dynamics [N·m·s/rad].

• twist::Float64: Current twist angle [rad].

• twist_ω::Float64: Current twist angular velocity [rad/s].

• tether_force::Float64: Tether force contribution [N].

• tether_moment::Float64: Tether moment contribution [N·m].

• aero_moment::Float64: Aerodynamic moment [N·m].

• unrefined_section_idxs::Vector{Int64}: Indices of VSM unrefined sections in this twist_surface.

• area::Float64: Surface area [m²] (flat-plate sections; NaN when unused).

TwistSurface(name, points, type, moment_frac; damping=50.0)

Constructs a TwistSurface object representing a collection of points on a kite body that share a common twist deformation.

TwistSurface geometry (lepos, chord, yairf) is computed later by SystemStructure using the closest VSM panel to the twist_surface's mean point position.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the twist_surface.
• points::Vector: References to points (names or indices).
• type::DynamicsType: DYNAMIC or QUASI_STATIC.
• moment_frac::SimFloat: Chordwise rotation point (0=LE, 1=TE).

Keyword Arguments

• damping::SimFloat=50.0: Damping coefficient for twist dynamics.
• x_airf=nothing: Chord-direction reference (body frame). When given, stored as the chord field — twist is measured relative to it. Defaults to auto-derived from the closest VSM panel during SystemStructure construction.
• y_airf=nothing: Spanwise reference (body frame). Auto-derived when omitted.
• area=NaN: Surface area [m²] for flat-plate (AeroPlate) sections.
• twist=0.0: Initial twist angle [rad] (prescribed input for FIXED sections).

Returns

• TwistSurface: A new TwistSurface object. The idx and point_idxs are resolved by SystemStructure. When x_airf/y_airf are omitted the geometry fields (lepos, chord, yairf) are computed during SystemStructure construction from the closest VSM panel.

mutable struct Segment

A segment representing a spring-damper connection from one point to another.

The spring-damper model uses per-unit-length stiffness and damping:

• Effective stiffness: k = unit_stiffness / length [N/m]
• Effective damping: c = unit_damping / length [N·s/m]

• idx::Int64: Index in the segments vector (assigned by SystemStructure).

• name::Union{Nothing, Int64, Symbol}

• point_idxs::Tuple{Int64, Int64}: Resolved endpoint indices (filled by SystemStructure).

• point_refs::Tuple{Union{Int64, Symbol}, Union{Int64, Symbol}}

• unit_stiffness::Float64: Stiffness per unit length [N]. Effective k = unit_stiffness/length [N/m].

• unit_damping::Float64: Damping per unit length [N·s]. Effective c = unit_damping/length [N·s/m].

• l0::Float64: Rest (unstretched) length [m].

• compression_frac::Float64: Compressive/tensile stiffness ratio (0-1). 0 = no compression stiffness.

• diameter::Float64: Segment diameter [m].

• len::Float64: Current length [m] (updated during simulation).

• force::Float64: Current force [N] (updated during simulation).

Segment(name, set, point_i, point_j; l0, compression_frac,
        diameter_mm, unit_stiffness, unit_damping)

Constructs a Segment using settings for material properties.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the segment.
• set::Settings: The settings object containing material properties.
• point_i, point_j: References to the two endpoint points (names or indices).

Keyword Arguments

• l0::SimFloat=zero(SimFloat): Unstretched length [m]. Calculated from point positions if zero.
• compression_frac::SimFloat=0.0: Compressive/tensile stiffness ratio (0-1). 0 = no compression stiffness.
• diameter_mm::Float64=NaN: Tether diameter [mm]. If NaN, uses set.d_tether.
• unit_stiffness::Float64=NaN: Stiffness per unit length [N]. Effective k = unit_stiffness/length.
• unit_damping::Float64=NaN: Damping per unit length [N·s]. Effective c = unit_damping/length.

Segment(name, point_i, point_j, unit_stiffness, unit_damping, diameter; l0, compression_frac)

Basic constructor for a Segment object.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the segment.
• point_i, point_j: References to the two endpoint points (names or indices).
• unit_stiffness: Stiffness per unit length [N]. Effective k = unit_stiffness/length [N/m].
• unit_damping: Damping per unit length [N·s]. Effective c = unit_damping/length [N·s/m].
• diameter: Segment diameter [m].

mutable struct Pulley

A pulley described by two segments with the common point of the segments being the pulley.

• idx::Int64: Index in the pulleys vector (assigned by SystemStructure).

• name::Union{Nothing, Int64, Symbol}

• segment_idxs::Tuple{Int64, Int64}: Resolved segment indices (filled by SystemStructure).

• segment_refs::Tuple{Union{Int64, Symbol}, Union{Int64, Symbol}}

• type::DynamicsType

• sum_len::Float64: Sum of connected segment lengths [m].

• len::Float64: Current pulley length [m] (updated during simulation).

• vel::Float64: Current pulley velocity [m/s] (updated during simulation).

Pulley(name, segment_i, segment_j, type)

Constructs a Pulley object that enforces length redistribution between two segments.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the pulley.
• segment_i, segment_j: References to the two segments (names or indices).
• type::DynamicsType: Dynamics type (DYNAMIC or QUASI_STATIC).

mutable struct Tether

A collection of segments forming a flexible line.

Can be constructed two ways:

• Route 1 (explicit segments): Provide segment references directly.
• Route 2 (auto-generation): Provide start/end points and n_segments; intermediate points and segments are created by expand_auto_tethers!.

• idx::Int64: Index in the tethers vector (assigned by SystemStructure).

• name::Union{Nothing, Int64, Symbol}

• segment_idxs::Vector{Int64}: Resolved segment indices (filled by SystemStructure).

• segment_refs::Vector{Union{Int64, Symbol}}

• start_point_idx::Int64: Resolved start point index (filled by SystemStructure).

• start_point_ref::Union{Nothing, Int64, Symbol}

• end_point_idx::Int64: Resolved end point index (filled by SystemStructure).

• end_point_ref::Union{Nothing, Int64, Symbol}

• n_segments::Int64

• unit_stiffness::Float64

• unit_damping::Float64

• diameter::Float64

• stretched_len::Float64: Current stretched length [m] (updated during simulation).

• len::Float64: Unstretched tether length [m] (sum of segment l0). ODE state variable. Segment l0 = len / n_segments.

• init_stretched_len::Union{Nothing, Float64}: Initial stretched standoff [m] — the placed point geometry (Σ segment norms). Drives placement of root tethers. nothing = use the geometric (CAD) length, i.e. no scaling.

• init_tether_force::Union{Nothing, Float64}: Target initial spring force [N], default 0. reinit! solves the unstretched len from the placed stretched length: len = stretched · (1 − force/unit_stiffness). Mutually exclusive with init_stretch_frac.

• init_stretch_frac::Union{Nothing, Float64}: Initial unstretched/stretched length fraction. reinit! sets len = init_stretch_frac · stretched; 0.9 gives 10% pre-stretch, 1.0 no tension, >1.0 slack. Must be positive. Mutually exclusive with init_tether_force.

Tether(name, segments, stretched_length=nothing;
       start_point=nothing, end_point=nothing,
       tether_force=nothing, stretch_frac=nothing)

Route 1: Construct a Tether from explicit segment references.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the tether.
• segments::Vector: References to segments (names or indices).
• stretched_length=nothing: Stretched standoff [m] (placed point geometry). Drives placement of root tethers. nothing = use the geometric length.

Keyword Arguments

• start_point=nothing: Optional start point ref.
• end_point=nothing: Optional end point ref.
• tether_force=nothing: Target initial spring force [N], default 0.
• stretch_frac=nothing: Initial len/stretched fraction. Mutually exclusive with tether_force.

Tether(name, stretched_length=nothing;
       start_point, end_point, n_segments,
       unit_stiffness=NaN, unit_damping=NaN,
       diameter=NaN, tether_force=nothing, stretch_frac=nothing)

Route 2: Construct a Tether for auto-generation of intermediate points and segments by expand_auto_tethers!.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the tether.
• stretched_length=nothing: Stretched standoff [m] (placed point geometry). Drives placement of root tethers. nothing = use the geometric length.

Keyword Arguments

• start_point: Reference to the start point (required).
• end_point: Reference to the end point (required).
• n_segments::Int: Number of segments to generate (required).
• unit_stiffness::Float64=NaN: Per-unit-length stiffness [N]. NaN = derive from Settings during auto-expansion.
• unit_damping::Float64=NaN: Per-unit-length damping [N·s]. NaN = derive from Settings during auto-expansion.
• diameter::Float64=NaN: Tether diameter [m]. NaN = derive from Settings during auto-expansion.
• tether_force=nothing: Target initial spring force [N], default 0.
• stretch_frac=nothing: Initial len/stretched fraction. Mutually exclusive with tether_force.

mutable struct Winch

A set of tethers (or a single tether) connected to a winch mechanism.

• idx::Int64: Index in the winches vector (assigned by SystemStructure).

• name::Union{Nothing, Int64, Symbol}

• tether_idxs::Vector{Int64}: Resolved tether indices (filled by SystemStructure).

• tether_refs::Vector{Union{Int64, Symbol}}

• winch_point_idx::Int64: Resolved winch point index (filled by SystemStructure).

• winch_point_ref::Union{Int64, Symbol}

• init_vel::Float64: Initial reel-out velocity [m/s]. Applied on reinit!.

• vel::Float64: Current reel-out velocity [m/s]. ODE state variable.

• acc::Float64: Current winch acceleration [m/s²] from motor dynamics.

• set_value::Float64: Abstract setpoint passed to the winch component as the set_value connector. Interpretation is the component's choice (e.g. motor torque, current, set velocity, set length). The default component treats it as motor torque [N·m].

• brake::Float64: Brake input in [0, 1]. The outer integrator freezes winch_vel and tether_len when > 0.5; custom components may interpret intermediate values as a continuous brake.

• speed_controlled::Bool: If true, reel-out velocity is prescribed externally rather than integrated from motor dynamics: winch acceleration is forced to 0 (ignoring model). Set the velocity via winch.vel.

• force::StaticArraysCore.MVector{3, Float64}

• gear_ratio::Float64: Gear ratio [-].

• drum_radius::Float64: Drum radius [m].

• f_coulomb::Float64: Coulomb friction force [N].

• c_vf::Float64: Viscous friction coefficient [N·s/m].

• inertia_total::Float64: Total rotational inertia [kg·m²].

• friction::Float64: Current friction force [N] (updated during simulation).

• friction_epsilon::Float64: Smoothing width for Coulomb friction sign function.

• model::Function: Builder function for the winch component. Called as model(system, winch_idx; name) -> ODESystem. Defaults to default_winch_component.

Winch(name, set, tethers; winch_point, ...)

Constructs a Winch object that controls tether length through torque or speed regulation.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the winch.
• set::Settings: Settings object for winch parameters.
• tethers::Vector: References to tethers connected to this winch (names or indices).

Keyword Arguments

• winch_point: Reference to the ground attachment point (name or index). Required.
• init_vel::SimFloat=0.0: Initial reel-out rate [m/s].
• brake=0.0: Brake input in [0, 1]. > 0.5 engages a hard freeze on winch_vel and tether_len at the outer integrator.
• speed_controlled::Bool=false: If true, prescribe reel-out velocity via winch.vel instead of integrating motor dynamics; winch acceleration is forced to 0, ignoring model.
• friction_epsilon::SimFloat=6.0: Smoothing parameter for Coulomb friction sign function.
• model::Function=default_winch_component: Builder returning the MTK component that defines the motor dynamics. See default_winch_component for the connector contract.

Winch(name, tethers, gear_ratio, drum_radius, f_coulomb,
      c_vf, inertia_total; winch_point, ...)

Constructs a Winch by directly providing physical parameters.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the winch.
• tethers::Vector: References to tethers (names or indices).
• gear_ratio, drum_radius, f_coulomb, c_vf, inertia_total: Physical parameters.

Keyword Arguments

• winch_point: Reference to ground attachment point. Required.
• init_vel::SimFloat=0.0: Initial reel-out rate [m/s].

abstract type AbstractWing

Abstract base type for all wing implementations.

Concrete subtypes must implement rigid body dynamics and provide a reference frame for attached points and twist_surfaces.

mutable struct Wing <: AbstractWing

A wing body that can have multiple twist_surfaces of points attached to it.

The wing provides a body reference frame for attached points and twistsurfaces. Points with type == WING move with the wing body according to the wing's orientation matrix `Rbtowand positionposw. Itsdynamicstypeselects rigid-body (RIGIDDYNAMICS) or per-particle (PARTICLEDYNAMICS) behaviour, and its [aero](@ref AbstractAeroModel) field selects the aerodynamic model. When the mode is a VSM mode ([AbstractVSMAero](@ref)) its [VSMEngine](@ref) fields (vsmwing,aerox`, …) are forwarded through the wing.

Special Properties

The wing's orientation can be accessed as a rotation matrix or a quaternion:

R_matrix = wing.R_b_to_w
wing.R_b_to_w = R_matrix

quat = wing.Q_b_to_w
wing.Q_b_to_w = quat

• idx::Int64

• name::Union{Nothing, Int64, Symbol}

• twist_surface_idxs::Vector{Int64}

• transform_idx::Int64

• twist_surface_refs::Vector{Union{Int64, Symbol}}

• transform_ref::Union{Int64, Symbol}

• R_b_to_c::Matrix{Float64}

• R_p_to_c::Matrix{Float64}

• R_b_to_p::Matrix{Float64}

• pos_cad::StaticArraysCore.MVector{3, Float64}

• com_offset_b::StaticArraysCore.MVector{3, Float64}

• inertia_principal::StaticArraysCore.MVector{3, Float64}

• dynamics_type::WingType

• aero::AbstractAeroModel

• com_w::StaticArraysCore.MVector{3, Float64}

• com_vel::StaticArraysCore.MVector{3, Float64}

• Q_p_to_w::Vector{Float64}

• ω_p::StaticArraysCore.MVector{3, Float64}

• Q_b_to_w::Vector{Float64}

• ω_b::StaticArraysCore.MVector{3, Float64}

• pos_w::StaticArraysCore.MVector{3, Float64}

• vel_w::StaticArraysCore.MVector{3, Float64}

• acc_w::StaticArraysCore.MVector{3, Float64}

• wind_disturb::StaticArraysCore.MVector{3, Float64}

• drag_frac::Float64

• va_b::StaticArraysCore.MVector{3, Float64}

• v_wind::StaticArraysCore.MVector{3, Float64}

• aero_force_b::StaticArraysCore.MVector{3, Float64}

• aero_moment_b::StaticArraysCore.MVector{3, Float64}

• tether_moment::StaticArraysCore.MVector{3, Float64}

• tether_force::StaticArraysCore.MVector{3, Float64}

• elevation::Float64

• elevation_vel::Float64

• elevation_acc::Float64

• azimuth::Float64

• azimuth_vel::Float64

• azimuth_acc::Float64

• heading::Float64

• turn_rate::StaticArraysCore.MVector{3, Float64}

• turn_acc::StaticArraysCore.MVector{3, Float64}

• course::Float64

• aoa::Float64

• fix_sphere::Bool

• group_points_moment::Bool: Whether in-group (twist_surface) points contribute their moment to the wing body.

• y_damping::Float64

• angular_damping::Float64

• z_disturb::Float64

• mass::Float64

• z_ref_points::Union{Nothing, Tuple{WeightedRefPoints, WeightedRefPoints}}

• y_ref_points::Union{Nothing, Tuple{WeightedRefPoints, WeightedRefPoints}}

• origin::Union{Nothing, WeightedRefPoints}

mutable struct VSMEngine{BA, W, SL}

Vortex Step Method aerodynamic engine carried by a VSM aero mode (AbstractVSMAero engine field). Holds the VortexStepMethod objects, the linearization state, and the structural↔panel mapping.

Fields

• vsm_aero, vsm_wing, vsm_solver: VortexStepMethod objects.
• aero_y: operating-point inputs [alpha, beta, ω1, ω2, ω3, twist...].
• aero_x: baseline wind-axis coefficients [CL, CD, CS, CM1, CM2, CM3, cm...].
• aero_jac: dense Jacobian d(aero_x)/d(aero_y).
• point_to_vsm_point, wing_segments: PARTICLE_DYNAMICS structural↔panel maps.
• aero_scale_chord: force scale compensating chord-length error (PARTICLE).
• aero_z_offset: body-frame z-shift of VSM panels (RIGID).

VSMWing(name, set, twist_surfaces, vsm_set; transform=nothing, y_damping=150.0, ...)

Construct a Wing with Vortex Step Method aerodynamics. Builds the VSMEngine (vsm_wing/vsm_aero/vsm_solver) internally and attaches it to the wing.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the wing.
• set::Settings: Settings object for VSM configuration.
• twist_surfaces::Vector: References to twist_surfaces (names or indices).
• vsm_set: VSM settings for engine creation. Required for VSM-backed aero modes (AbstractVSMAero); may be nothing for engine-less modes like AeroNone.

Keyword Arguments

• transform=nothing: Reference to the transform. Defaults to 1.
• R_b_to_c, pos_cad, inertia_diag: Geometry placeholders (resolved later).
• y_damping, angular_damping: Damping coefficients.
• dynamics_type::WingType=RIGID_DYNAMICS: Aerodynamic model type.
• aero::AbstractAeroModel: Aerodynamic model (defaults by dynamics_type).
• group_points_moment::Bool=true: When false, in-group (twist_surface) points add no moment to the wing body; their force still contributes. Runtime-switchable.
• point_to_vsm_point, wing_segments: VSM structural↔panel maps.
• z_ref_points, y_ref_points, origin: Body-frame references.
• aero_scale_chord, aero_z_offset: VSM force/panel adjustments.

VSMWing(name, vsm_aero, vsm_wing, vsm_solver, twist_surfaces, R_b_to_c, pos_cad; transform=nothing)

Construct a RIGID_DYNAMICS Wing from pre-created VSM objects. Kept for backward compatibility with predefined structures.

PlateWing(name, twist_surfaces, calc_cl, calc_cd;
          dynamics_type=PARTICLE_DYNAMICS, transform=nothing,
          y_damping=150.0, angular_damping=0.0, drag_corr=0.93,
          z_ref_points=nothing, y_ref_points=nothing, origin=nothing)

Construct a flat-plate Wing (no VSM engine; vsm === nothing). Each flat-plate section is a 1-point FIXED TwistSurface carrying the section's body-frame reference frame, area, and prescribed twist; the shared polar lookups live on the wing's AeroPlate aero model. Supports both RIGID_DYNAMICS and PARTICLE_DYNAMICS.

Arguments

• name: Wing name/identifier.
• twist_surfaces: References (names or indices) to the wing's flat-plate sections — each a 1-point FIXED TwistSurface.
• calc_cl: CL lookup callable(alpha_deg) → CL.
• calc_cd: CD lookup callable(alpha_deg) → CD.

Keyword Arguments

• dynamics_type: RIGID_DYNAMICS or PARTICLE_DYNAMICS (default).
• transform: Reference to transform (name or index).
• y_damping, angular_damping: Damping coefficients.
• drag_corr: Drag correction factor (stored on the AeroPlate model).
• z_ref_points, y_ref_points, origin: Body-frame references.

create_plate_interpolations(alpha_deg, cl_data, cd_data;
    alpha_cd=nothing, spline=:cubic)

Create CL and CD interpolation objects from polar data vectors.

Arguments

• alpha_deg: angle of attack values [deg]
• cl_data: lift coefficient values
• cd_data: drag coefficient values
• alpha_cd: separate alpha values for CD (default: same as CL)
• spline: :cubic for cubic spline, :linear for piecewise linear

Returns

• (cl_interp, cd_interp) tuple of interpolation objects

mutable struct Transform

Describes the spatial transformation (position and orientation) of system components relative to a base reference point.

• idx::Int64: Index in the transforms vector (assigned by SystemStructure).

• name::Union{Nothing, Int64, Symbol}

• wing_idx::Union{Nothing, Int64}: Resolved wing index (filled by SystemStructure).

• wing_ref::Union{Nothing, Int64, Symbol}

• rot_point_idx::Union{Nothing, Int64}: Resolved rotation point index (filled by SystemStructure).

• rot_point_ref::Union{Nothing, Int64, Symbol}

• base_point_idx::Union{Nothing, Int64}: Resolved base point index (filled by SystemStructure).

• base_point_ref::Union{Nothing, Int64, Symbol}

• base_transform_idx::Union{Nothing, Int64}: Resolved base transform index (filled by SystemStructure).

• base_transform_ref::Union{Nothing, Int64, Symbol}

• elevation::Float64: Elevation angle [rad].

• azimuth::Float64: Azimuth angle [rad].

• heading::Float64: Heading angle [rad].

• elevation_vel::Float64: Angular velocity in elevation direction [rad/s].

• azimuth_vel::Float64: Angular velocity in azimuth direction [rad/s].

• turn_rate::Float64: Angular velocity around radial axis [rad/s].

• base_pos::Union{Nothing, StaticArraysCore.MVector{3, Float64}}: Base position [m]. Nothing = derived from base_transform.

Transform(name, elevation, azimuth, heading; base_point, base_pos, base_transform, wing, rot_point)

Constructs a Transform object that orients system components using spherical coordinates.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the transform.
• elevation, azimuth, heading: Spherical coordinates [rad].

Keyword Arguments

Base Reference (choose one method):

• base_pos & base_point: Use a fixed position and a reference point.
• base_transform: Chain to another transform's position.

Target Object (choose one):

• wing: Reference to the wing to position at (elevation, azimuth).
• rot_point: Reference to the point to position at (elevation, azimuth).

NamedCollection{T} <: AbstractVector{T}

A wrapper around a vector that enables both numeric and symbolic indexing.

By subtyping AbstractVector, this type works transparently with all existing code that expects vectors, including @unpack macros and iteration.

Names are extracted from items that have a name field. Items without names (or with name=nothing) are only accessible by numeric index.

• items::Vector: The underlying vector of items

• name_to_idx::Dict{Symbol, Int64}: Mapping from symbolic names to indices

NameRef = Union{Int, Symbol}

A reference to another component, either by symbolic name (:ground) or integer index (1).

Name resolution

Components reference each other by name or index at construction time. These are stored in _ref fields (e.g. point_refs, wing_ref). During SystemStructure construction, assign_indices_and_resolve! maps every ref to a numeric index via build_name_dict (name → vector position) and stores the result in the corresponding _idx fields (e.g. point_idxs, wing_idx).

Each component has a name field (const, set once at construction) that identifies it for lookup. The type includes Nothing for forward-compatibility but no public constructor produces name=nothing; a nothing-named component would simply be unreferenceable by name (only by vector index).

SysState(s::SymbolicAWEModel, zoom=1.0)

Constructs a SysState object from a SymbolicAWEModel.

This is a convenience constructor that creates a new SysState object and populates it with the current state of the provided model.

Arguments

• s::SymbolicAWEModel: The source model.
• zoom::SimFloat=1.0: A scaling factor for the position coordinates.

Returns

• SysState: A new state struct representing the current model state.

update_sys_state!(ss::SysState, s::SymbolicAWEModel, zoom=1.0)

Updates a SysState object with the current state values from the SymbolicAWEModel.

This function takes the raw data from the model's internal integrator and populates the fields of the user-friendly SysState struct, converting units (e.g., radians to degrees) and calculating derived values like AoA and roll/pitch/yaw angles.

Arguments

• ss::SysState: The state struct to be updated.
• s::SymbolicAWEModel: The source model.
• zoom::SimFloat=1.0: A scaling factor for the position coordinates.

update_sys_state!(sys_state, y::AbstractVector, sam::SymbolicAWEModel, t::Real)

Update a SysState for a linear state-space simulation, using output y and model sam.

update_from_sysstate!(sys::SystemStructure, sys_state::SysState)

Update the dynamic state of a SystemStructure from a SysState snapshot.

This function copies the state variables that are present in SysState (such as point positions, wing orientations, winch lengths, and twist angles) into an existing SystemStructure. Fields that cannot be populated from SysState (such as aerodynamic forces, moments, and segment forces) are set to NaN to prevent them from being plotted.

This is useful for visualizing a SysLog by extracting individual SysState snapshots and applying them to a SystemStructure for plotting with the Makie extension.

Arguments

• sys::SystemStructure: The system structure to update (must already exist with correct topology).
• sys_state::SysState: The state snapshot to copy from.

Example

# Load a system log
sim_log = load_log(...)

# Create a SystemStructure with the same topology
sys = SystemStructure(se(), "ram")

# Update from a specific time step
update_from_sysstate!(sys, sim_log.syslog[100])

# Plot the system at that time step
plot(sys)

Notes

• The SystemStructure must have been created with the same model configuration as the simulation that generated the SysLog.
• Aerodynamic and force fields are set to NaN and will not be plotted.
• The number of points in sys must match the parametric type P of SysState{P}.