SegmentType `POWER_LINE` `STEERING_LINE` `BRIDLE`

Enumeration for the type of a tether segment.

Elements

• POWER_LINE: A segment belonging to a main power line.
• STEERING_LINE: A segment belonging to a steering line.
• BRIDLE: A segment belonging to the bridle system.

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

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

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.

WingType `QUATERNION` `REFINE`

Enumeration for the aerodynamic model type of a wing.

Elements

• QUATERNION: Wing uses quaternion-based rigid body dynamics with twist groups. Aerodynamic forces/moments are applied to the wing center of mass.
• REFINE: 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.

AeroMode `AERO_NONE` `AERO_DIRECT` `AERO_LINEARIZED`

Enumeration for how aerodynamic forces enter the ODE system. Orthogonal to WingType — determines the aero computation strategy at runtime.

Elements

• AERO_NONE: No aerodynamic forces (returns zeros). For debugging rigid body dynamics.
• AERO_DIRECT: Stored forces from nonlinear VSM solve, piecewise-constant between updates.
• AERO_LINEARIZED: First-order Taylor expansion using Jacobian from VSM linearization.

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.

• set::Settings: Reference to the settings struct

• 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)

• set_tether_len::Vector{Float64}: Vector of tether length set-points Default: zeros(SimFloat, 3)

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.
• Group: Collections of points for wing deformation.
• Segment: Spring-damper elements.
• Pulley: Elements that redistribute line lengths.
• Tether: Groups of segments controlled by a winch.
• Winch: Ground-based winches.
• Wing: Rigid wing bodies.
• Transform: Spatial transformations for initial positioning.

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

Constructs a SystemStructure object representing a complete kite system.

Physical Models

• "ram": A model with 4 deformable wing groups and a complex pulley bridle system.
• "simple_ram": A model with 4 deformable wing groups 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, groups, 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

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

• transform_idx::Int64

• wing_idx::Int64

• 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}

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

• type::DynamicsType

• extra_mass::Float64

• total_mass::Float64

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

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

• area::Float64

• drag_coeff::Float64

• fix_sphere::Bool

• fix_static::Bool

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 Group

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

• idx::Int64

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

• point_idxs::Vector{Int64}

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

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

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

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

• type::DynamicsType

• moment_frac::Float64

• damping::Float64

• twist::Float64

• twist_ω::Float64

• tether_force::Float64

• tether_moment::Float64

• aero_moment::Float64

• unrefined_section_idxs::Vector{Int64}

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

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

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

Arguments

• name::Union{Int, Symbol}: Name/identifier for the group.
• 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.

Returns

• Group: A new Group object. The idx and point_idxs are resolved by SystemStructure. Geometry fields (lepos, chord, yairf) are initialized to zero and 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

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

• point_idxs::Tuple{Int64, Int64}

• 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: Stiffness reduction factor when segment is in compression (0-1).

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

• len::Float64: Current length of the segment [m].

• force::Float64: Current force in the segment [N].

Segment(name, set, point_i, point_j, type; l0, compression_frac, 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).
• type::SegmentType: Type of the segment (POWER_LINE, STEERING_LINE, BRIDLE).

Keyword Arguments

• l0::SimFloat=zero(SimFloat): Unstretched length [m]. Calculated from point positions if zero.
• compression_frac::SimFloat=0.0: Stiffness reduction factor in compression.
• diameter_mm::Float64=NaN: Tether diameter [mm]. If NaN, uses default from settings.
• 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

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

• segment_idxs::Tuple{Int64, Int64}

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

• type::DynamicsType

• sum_len::Float64

• len::Float64

• vel::Float64

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 that are controlled together by a winch.

• idx::Int64

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

• segment_idxs::Vector{Int64}

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

• winch_point_idx::Int64

• winch_point_ref::Union{Int64, Symbol}

• stretched_len::Float64

Tether(name, segments; winch_point=nothing)

Constructs a Tether object representing a flexible line composed of multiple segments.

Arguments

• name::Union{Int, Symbol}: Name/identifier for the tether.
• segments::Vector: References to segments that form this tether (names or indices).

Keyword Arguments

• winch_point=nothing: Reference to the ground point where tether attaches to winch. Defaults to point 1 if not specified.

mutable struct Winch

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

• idx::Int64

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

• tether_idxs::Vector{Int64}

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

• tether_len::Union{Nothing, Float64}

• tether_vel::Float64

• tether_acc::Float64

• set_value::Float64

• brake::Bool

• speed_controlled::Bool

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

• gear_ratio::Float64

• drum_radius::Float64

• f_coulomb::Float64

• c_vf::Float64

• inertia_total::Float64

• friction::Float64

• friction_epsilon::Float64

Winch(name, set, tethers; tether_len=0.0, tether_vel=0.0, brake=false, speed_controlled=false)

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: The main settings object, used to retrieve winch parameters.
• tethers::Vector: References to tethers connected to this winch (names or indices).

Keyword Arguments

• tether_len::SimFloat=0.0: Initial tether length [m].
• tether_vel::SimFloat=0.0: Initial tether velocity (reel-out rate) [m/s].
• brake::Bool=false: If true, the winch brake is engaged.
• speed_controlled::Bool=false: If true, tether velocity is prescribed externally (not integrated by the ODE). D(tether_vel) = 0, length still tracks velocity.
• friction_epsilon::SimFloat=6.0: Smoothing parameter for sign function in Coulomb friction.

Winch(name, tethers, gear_ratio, drum_radius, f_coulomb, c_vf, inertia_total; tether_len=0.0, tether_vel=0.0, brake=false, speed_controlled=false)

Constructs a Winch object by directly providing its physical parameters.

Arguments

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

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 groups.

mutable struct BaseWing <: AbstractWing

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

The wing provides a rigid body reference frame for attached points and groups. Points with type == WING move rigidly with the wing body according to the wing's orientation matrix R_b_to_w and position pos_w.

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}

• group_idxs::Vector{Int64}

• transform_idx::Int64

• group_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}

• wing_type::WingType

• aero_mode::AeroMode

• 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

• y_damping::Float64

• angular_damping::Float64

• z_disturb::Float64

• mass::Float64

mutable struct VSMWing <: AbstractWing

A wing that uses the Vortex Step Method (VSM) for aerodynamic computations.

This struct extends the base wing functionality with VSM-specific aerodynamic modeling capabilities, including vortex wake computations and aerodynamic loads.

• base::BaseWing

• vsm_aero::BodyAerodynamics

• vsm_wing::VortexStepMethod.AbstractWing

• vsm_solver::Solver

• vsm_y::Vector{Float64}

• vsm_x::Vector{Float64}

• vsm_jac::Matrix{Float64}

• point_to_vsm_point::Union{Nothing, Dict{Int64, Tuple{Int64, Symbol}}}

• wing_segments::Union{Nothing, Vector{Tuple{Int64, Int64}}}

• z_ref_points::Union{Nothing, Tuple{Union{Int64, Vector{Int64}}, Union{Int64, Vector{Int64}}}}

• y_ref_points::Union{Nothing, Tuple{Union{Int64, Vector{Int64}}, Union{Int64, Vector{Int64}}}}

• z_ref_points_ref::Union{Nothing, Tuple{Union{Int64, Symbol, Vector{Union{Int64, Symbol}}}, Union{Int64, Symbol, Vector{Union{Int64, Symbol}}}}}

• y_ref_points_ref::Union{Nothing, Tuple{Union{Int64, Symbol, Vector{Union{Int64, Symbol}}}, Union{Int64, Symbol, Vector{Union{Int64, Symbol}}}}}

• origin_idx::Union{Nothing, Int64}

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

• aero_scale_chord::Float64

• aero_z_offset::Float64

mutable struct Transform

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

• idx::Int64

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

• wing_idx::Union{Nothing, Int64}

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

• rot_point_idx::Union{Nothing, Int64}

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

• base_point_idx::Union{Nothing, Int64}

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

• base_transform_idx::Union{Nothing, Int64}

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

• elevation::Float64

• azimuth::Float64

• heading::Float64

• elevation_vel::Float64

• azimuth_vel::Float64

• turn_rate::Float64

• base_pos::Union{Nothing, StaticArraysCore.MVector{3, Float64}}

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).

Transform(name, set, base_point; kwargs...)

Constructor helper to create a Transform from a Settings object. Note: Uses idx=1 for settings indexing (legacy compatibility).

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

Reference type that can be an integer index or a symbolic name

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.

SysState(y::AbstractVector, sam::SymbolicAWEModel, t::Real; zoom=1.0)

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

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!(ss::SysState, y::AbstractVector, sam::SymbolicAWEModel, t::Real;
                  zoom=1.0)

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

update_from_sysstate!(sys::SystemStructure, ss::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).
• ss::SysState: The state snapshot to copy from.

Example

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

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

# Update from a specific time step
update_from_sysstate!(sys, lg.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}.