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

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

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

• idx::Int64: Index in the groups 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 group.

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: 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_unstretched_len::Float64: Initial unstretched length [m]. Used by reinit! to reset len. Segment l0 = initunstretchedlen / n_segments.

• init_stretched_len::Union{Nothing, Float64}: Initial stretched length [m]. Point positions scaled to this value by apply_tether_init_stretched_lens!. nothing = use CAD length.

Tether(name, segments, unstretched_length;
       start_point=nothing, end_point=nothing,
       stretched_length=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).
• unstretched_length: Rope length [m]. Sets segment l0 = unstretchedlength / nsegments.

Keyword Arguments

• start_point=nothing: Optional start point ref.
• end_point=nothing: Optional end point ref.
• stretched_length=nothing: Point positioning target [m]. nothing = skip position scaling.

Tether(name, unstretched_length;
       start_point, end_point, n_segments,
       unit_stiffness=NaN, unit_damping=NaN,
       diameter=NaN, stretched_length=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.
• unstretched_length: Rope length [m]. Sets segment l0 = unstretchedlength / nsegments.

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.
• stretched_length=nothing: Point positioning target [m]. nothing = skip position scaling.

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: Control input value (torque [N·m] or speed [m/s]).

• brake::Bool: If true, brake is engaged.

• speed_controlled::Bool: If true, velocity is prescribed (not integrated).

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

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::Bool=false: If true, brake is engaged.
• speed_controlled::Bool=false: If true, velocity is prescribed (not integrated).
• friction_epsilon::SimFloat=6.0: Smoothing parameter for Coulomb friction sign function.

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 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{WeightedRefPoints, WeightedRefPoints}}

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

• 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: 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!(ss, 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, 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}.