Model VSM LLT

Enumeration of the implemented model types.

Elements

• VSM: Vortex Step Method
• LLT: Lifting Line Theory

WingType `RECTANGULAR` `CURVED` `ELLIPTICAL`

Enumeration of the implemented wing types.

Elements:

• RECTANGULAR
• CURVED
• ELLIPTICAL

AeroModel LEI_AIRFOIL_BREUKELS POLAR_VECTORS POLAR_MATRICES INVISCID

Enumeration of the implemented aerodynamic models. See also: AeroData

Elements

• LEI_AIRFOIL_BREUKELS: Polynom approximation for leading edge inflatable kites
• POLAR_VECTORS: Polar vectors as function of alpha (lookup tables with interpolation)
• POLAR_MATRICES: Polar matrices as function of alpha and delta (lookup tables with interpolation)
• INVISCID

where alpha is the angle of attack, delta is trailing edge angle.

PanelDistribution LINEAR COSINE SPLIT_PROVIDED UNCHANGED

Enumeration of the implemented panel distributions.

Elements

• LINEAR # Linear distribution
• COSINE # Cosine distribution
• SPLIT_PROVIDED # Split provided sections
• UNCHANGED # 1:1 copy of unrefined to refined sections (no interpolation)

InitialGammaDistribution ELLIPTIC ZEROS

Enumeration of the implemented initial gamma distributions.

Elements

• ELLIPTIC
• ZEROS

SolverType

Enumeration specifying the method used to solve for circulation distribution.

Values

• LOOP: Converging gamma loop - iterative approach that repeatedly updates circulation values until convergence
• NONLIN: Nonlinear solver - uses a numerical solver to solve the circulation equations

SolverStatus FEASIBLE INFEASIBLE FAILURE

Enumeration to report back the validity of the result of the solve! function. Used in the VSMSolution struct.

Elements

• FEASIBLE: The gamma distribution is physically feasible
• INFEASIBLE: The gamma distribution is physically infeasible
• FAILURE: The result did not converge within the maximal number of iterations

const MVec3 = MVector{3, Float64}

Basic 3-dimensional vector, stack allocated, mutable.

const PosVector=Union{MVec3, Vector}

Position vector, either a MVec3 or a Vector for use in function signatures.

const VelVector=Union{MVec3, Vector}

Velocity vector, either a MVec3 or a Vector for use in function signatures.

AeroData= Union{
    Nothing,
    NTuple{2, Float64},
    Tuple{Vector{Float64}, Vector{Float64}, Vector{Float64}, Vector{Float64}},
    Tuple{Vector{Float64}, Vector{Float64}, Matrix{Float64}, Matrix{Float64}, Matrix{Float64}}
}

Union of different definitions of the aerodynamic properties of a wing section. See also: AeroModel

• nothing for INVISCID
• (tube_diameter, camber) for LEI_AIRFOIL_BREUKELS
• (alpha_range, cl_vector, cd_vector, cm_vector) for POLAR_VECTORS
• (alpha_range, delta_range, cl_matrix, cd_matrix, cm_matrix) for POLAR_MATRICES

where alpha is the angle of attack [rad], delta is trailing edge angle [rad], cl the lift coefficient, cd the drag coefficient and cm the pitching moment coefficient. The camber of a kite refers to the curvature of its airfoil shape. The camber is typically measured as the maximum distance between the mean camber line (the line equidistant from the upper and lower surfaces) and the chord line of the airfoil.

VSMSettings

Top-level settings container for a VortexStepMethod simulation. Can be constructed from keyword arguments or loaded from a YAML file with VSMSettings(filename).

Fields

• condition: [ConditionSettings] (wind speed, alpha, beta, yaw rate)
• wings: Vector of WingSettings
• solver_settings: SolverSettings

Example

settings = VSMSettings("vsm_settings.yaml")
wing = Wing(settings)

WingSettings

Settings for a single wing, used within VSMSettings.

Fields

• name: Wing identifier (default "main_wing")
• geometry_file: Path to wing geometry YAML file
• obj_file: Path to .obj geometry file
• dat_file: Path to .dat airfoil file
• n_panels: Number of panels (default 40)
• spanwise_panel_distribution: Panel distribution type (default LINEAR)
• spanwise_direction: Spanwise direction vector (default [0, 1, 0])
• remove_nan: Whether to remove NaN values from polar data (default true)
• use_prior_polar: Reuse prior refined/panel polar mapping on reinit/refine updates (default false)

SolverSettings

Solver configuration, used within VSMSettings.

Fields

• n_panels: Total number of panels (default 40)
• aerodynamic_model_type: VSM or LLT (default VSM)
• solver_type: "LOOP" or "NONLIN" (default "LOOP")
• density: Air density [kg/m³] (default 1.225)
• max_iterations: Maximum solver iterations (default 1500)
• rtol: Relative tolerance (default 1e-5)
• tol_reference_error: Reference error tolerance (default 0.001)
• relaxation_factor: Convergence relaxation factor (default 0.03)
• artificial_damping: Enable artificial damping (default false)
• k2, k4: Artificial damping parameters
• type_initial_gamma_distribution: ELLIPTIC or ZEROS (default ELLIPTIC)
• use_gamma_prev: Reuse provided previous gamma as initial guess when available (default true)
• core_radius_fraction: Vortex core radius fraction (default 1e-20)
• mu: Dynamic viscosity [N·s/m²] (default 1.81e-5)
• calc_only_f_and_gamma: Only output forces and circulation (default false)
• correct_aoa: Perform angle of attack correction (default false)

@with_kw mutable struct Section

Represents a wing section with leading edge, trailing edge, and aerodynamic properties.

Fields

• LE_point::MVec3 = zeros(MVec3): Leading edge point coordinates
• TE_point::MVec3 = zeros(MVec3): Trailing edge point coordinates
• aero_model::AeroModel = INVISCID: AeroModel
• aero_data::AeroData = nothing: See: AeroData

Section(LE_point::PosVector, TE_point::PosVector, aero_model)

Create a new wing section with the specified leading edge point, trailing edge point, and aerodynamic model.

Arguments

• LE_point::PosVector: Leading edge point coordinates
• TE_point::PosVector: Trailing edge point coordinates
• aero_model::AeroModel: Aerodynamic model type (e.g., INVISCID, POLAR_VECTORS)

Returns

• Section: A new section with the specified parameters and no aerodynamic data

Wing

Represents a wing composed of multiple sections with aerodynamic properties.

Core Fields (all wings)

• n_panels::Int16: Number of panels in aerodynamic mesh
• n_unrefined_sections::Int16: Number of unrefined sections (sections before mesh refinement)
• spanwise_distribution::PanelDistribution: PanelDistribution
• spanwise_direction::MVec3: Wing span direction vector
• sections::Vector{Section}: Vector of wing sections, see: Section
• refined_sections::Vector{Section}: Vector of refined wing sections, see: Section
• remove_nan::Bool: Wether to remove the NaNs from interpolations or not
• use_prior_polar::Bool: Keep previously-initialized section/panel polar data when refining geometry updates

Deformation Fields (optional, for deformable wings)

• non_deformed_sections::Vector{Section}: Original undeformed sections
• theta_dist::Vector{Float64}: Panel twist angle distribution
• delta_dist::Vector{Float64}: Trailing edge deflection distribution

Physical Properties (optional, for OBJ-based wings)

• mass::Float64: Total wing mass in kg (0.0 if not applicable)
• gamma_tip::Float64: Angular extent from center to wing tip (0.0 if not applicable)
• inertia_tensor::Matrix{Float64}: 3x3 inertia tensor (empty if not applicable)
• T_cad_body::MVec3: Translation from CAD to body frame (zeros if not applicable)
• R_cad_body::MMat3: Rotation from CAD to body frame (identity if not applicable)
• radius::Float64: Wing curvature radius (0.0 if not applicable)
• le_interp::Union{Nothing, NTuple{3, Extrapolation}}: Leading edge interpolation
• te_interp::Union{Nothing, NTuple{3, Extrapolation}}: Trailing edge interpolation
• area_interp::Union{Nothing, Extrapolation}: Area interpolation
• cache::Vector{PreallocationTools.LazyBufferCache{typeof(identity), typeof(identity)}}: Preallocated buffers

Wing(n_panels::Int;
     n_unrefined_sections=nothing,
     spanwise_distribution::PanelDistribution=LINEAR,
     spanwise_direction::PosVector=MVec3([0.0, 1.0, 0.0]),
     remove_nan::Bool=true,
     use_prior_polar::Bool=false)

Constructor for a Wing struct with default values that initializes the sections and refined sections as empty arrays. Creates a basic wing suitable for YAML-based construction.

Parameters

• n_panels::Int: Number of panels in aerodynamic mesh
• n_unrefined_sections::Int: Number of unrefined sections (inferred from added sections for YAML wings)
• spanwise_distribution::PanelDistribution = LINEAR: PanelDistribution
• spanwise_direction::MVec3 = MVec3([0.0, 1.0, 0.0]): Wing span direction vector
• remove_nan::Bool: Wether to remove the NaNs from interpolations or not
• use_prior_polar::Bool: Reuse prior refined/panel polar mapping during geometry-only updates

ObjWing(obj_path, dat_path; kwargs...)

Create a deformable wing model from 3D geometry (.obj) and airfoil data (.dat) files.

This constructor builds a complete aerodynamic model by:

1. Loading wing geometry from the .obj file
2. Creating aerodynamic polars from the airfoil .dat file (or loading existing)
3. Computing inertial properties and coordinate transformations
4. Setting up control surfaces and panel distribution

The resulting Wing supports deformation through unrefined_deform! and deform! functions.

Arguments

• obj_path: Path to .obj file containing 3D wing geometry
• dat_path: Path to .dat file containing 2D airfoil profile

Keyword Arguments

• crease_frac=0.9: Normalized trailing edge hinge location (0-1)
• wind_vel=10.0: Reference wind velocity for XFoil analysis (m/s)
• mass=1.0: Wing mass (kg)
• n_panels=56: Number of aerodynamic panels across wingspan
• n_unrefined_sections: Number of unrefined sections for deformation control (default: inferred from geometry)
• align_to_principal=false: Align body frame to principal axes of inertia
• spanwise_distribution=UNCHANGED: Panel distribution type (forced to UNCHANGED for ObjWing)
• remove_nan=true: Interpolate NaN values in aerodynamic data
• use_prior_polar=false: Reuse prior refined/panel polar mapping on geometry updates
• alpha_range=deg2rad.(-5:1:20): Angle of attack range for polars (rad)
• delta_range=deg2rad.(-5:1:20): Trailing edge deflection range for polars (rad)
• prn=true: Print informational messages

Returns

A fully initialized Wing instance ready for aerodynamic simulation with deformation support.

Example

# Create a deformable wing from geometry files
wing = ObjWing(
    "path/to/wing.obj",
    "path/to/airfoil.dat";
    mass=1.5,
    n_panels=40,
    n_unrefined_sections=4
)

# Apply deformation
unrefined_deform!(wing, deg2rad.([5, 10, 5, 0]), deg2rad.([-5, 0, -5, 0]))

ObjWing(obj_path, dat_path; kwargs...)

Create a deformable wing model from 3D geometry (.obj) and airfoil data (.dat) files.

This constructor builds a complete aerodynamic model by:

1. Loading wing geometry from the .obj file
2. Creating aerodynamic polars from the airfoil .dat file (or loading existing)
3. Computing inertial properties and coordinate transformations
4. Setting up control surfaces and panel distribution

The resulting Wing supports deformation through unrefined_deform! and deform! functions.

Arguments

• obj_path: Path to .obj file containing 3D wing geometry
• dat_path: Path to .dat file containing 2D airfoil profile

Keyword Arguments

• crease_frac=0.9: Normalized trailing edge hinge location (0-1)
• wind_vel=10.0: Reference wind velocity for XFoil analysis (m/s)
• mass=1.0: Wing mass (kg)
• n_panels=56: Number of aerodynamic panels across wingspan
• n_unrefined_sections: Number of unrefined sections for deformation control (default: inferred from geometry)
• align_to_principal=false: Align body frame to principal axes of inertia
• spanwise_distribution=UNCHANGED: Panel distribution type (forced to UNCHANGED for ObjWing)
• remove_nan=true: Interpolate NaN values in aerodynamic data
• use_prior_polar=false: Reuse prior refined/panel polar mapping on geometry updates
• alpha_range=deg2rad.(-5:1:20): Angle of attack range for polars (rad)
• delta_range=deg2rad.(-5:1:20): Trailing edge deflection range for polars (rad)
• prn=true: Print informational messages

Returns

A fully initialized Wing instance ready for aerodynamic simulation with deformation support.

Example

# Create a deformable wing from geometry files
wing = ObjWing(
    "path/to/wing.obj",
    "path/to/airfoil.dat";
    mass=1.5,
    n_panels=40,
    n_unrefined_sections=4
)

# Apply deformation
unrefined_deform!(wing, deg2rad.([5, 10, 5, 0]), deg2rad.([-5, 0, -5, 0]))

@with_kw mutable struct BodyAerodynamics{P}

Main structure for calculating aerodynamic properties of bodies. Use the constructor to initialize.

Fields

• panels::Vector{Panel}: Vector of refined Panel structs
• wings::Vector{Wing}: A vector of wings; a body can have multiple wings
• va::MVec3 = zeros(MVec3): A vector of the apparent wind speed, see: MVec3
• omega::MVec3 = zeros(MVec3): A vector of the turn rates around the kite body axes
• gamma_distribution=zeros(Float64, P): A vector of the circulation of the velocity field; Length: Number of segments. [m²/s]
• alpha_uncorrected=zeros(Float64, P): angles of attack per panel
• alpha_corrected=zeros(Float64, P): corrected angles of attack per panel
• stall_angle_list=zeros(Float64, P): stall angle per panel
• alpha_dist::MVector{P, Float64} = zeros(Float64, P)
• v_a_dist::MVector{P, Float64} = zeros(Float64, P)
• work_vectors::NTuple{10, MVec3} = ntuple(_ -> zeros(MVec3), 10)
• AIC::Array{Float64, 3} = zeros(3, P, P)
• projected_area::Float64 = 1.0: The area projected onto the xy-plane of the kite body reference frame [m²]
• c_ref::Float64 = 1.0: Reference chord length (max panel chord) [m]
• y::MVector{P, Float64} = MVector{P,Float64}(zeros(P))
• cache::Vector{PreallocationTools.LazyBufferCache{typeof(identity), typeof(identity)}} = [LazyBufferCache() for _ in 1:15]

Solver

Main solver structure for the Vortex Step Method.See also: solve

Attributes

General settings

• aerodynamic_model_type::Model = VSM: The model type, see: Model
• density::Float64 = 1.225: Air density [kg/m³]
• max_iterations::Int64 = 1500
• rtol::Float64 = 1e-5: relative error
• tol_reference_error::Float64 = 0.001
• relaxation_factor::Float64 = 0.03: Relaxation factor for convergence

Damping settings

• is_with_artificial_damping::Bool = false: Whether to apply artificial damping
• artificial_damping::NamedTuple{(:k2, :k4), Tuple{Float64, Float64}} = (k2=0.1, k4=0.0): Artificial damping parameters

Additional settings

• type_initial_gamma_distribution::InitialGammaDistribution = ELLIPTIC: see: InitialGammaDistribution
• use_gamma_prev::Bool = true: reuse provided previous gamma as initial guess when available
• core_radius_fraction::Float64 = 1e-20:
• mu::Float64 = 1.81e-5: Dynamic viscosity [N·s/m²]
• is_only_f_and_gamma_output::Bool = false: Whether to only output f and gamma
• reference_point::MVec3 = [0.0, 0.0, 0.0]: Moment reference point in body frame

Solution

sol::VSMSolution = VSMSolution(): The result of calling solve!

VSMSolution

Struct for storing the solution of the solve! function. Must contain all info needed by KiteModels.jl.

Naming Convention

• Variables ending in _dist: Per-panel distributions (length P, one value per panel)
• Variables ending in _unrefined_dist: Per-unrefined-section distributions (length U, averaged values per unrefined section)

Attributes

• width_dist::Vector{Float64}: Width of the panels [m]
• alpha_dist::Vector{Float64}: Angle of attack of each panel relative to the apparent wind [rad]
• cl_dist::Vector{Float64}: Lift coefficients of the panels [-]
• cd_dist::Vector{Float64}: Drag coefficients of the panels [-]
• cm_dist::Vector{Float64}: Pitching moment coefficients of the panels [-]
• lift_dist::Vector{Float64}: Lift force of the panels [N]
• drag_dist::Vector{Float64}: Drag force of the panels [N]
• panelmomentdist::Vector{Float64}: Pitching moment around the spanwise vector of the panels [Nm]
• f_body_3D::Matrix{Float64}: Matrix of the aerodynamic forces (x, y, z vectors) [N]
• m_body_3D::Matrix{Float64}: Matrix of the aerodynamic moments [Nm]
• gamma_distribution::Union{Nothing, Vector{Float64}}: Vector containing the panel circulations.
• force::MVec3: Aerodynamic force vector in KB reference frame [N]
• moment::MVec3: Aerodynamic moments [Mx, My, Mz] around the reference point [Nm]
• force_coeffs::MVec3: Aerodynamic force coefficients [CFx, CFy, CFz] [-]
• moment_coeffs::MVec3: Aerodynamic moment coefficients [CMx, CMy, CMz] [-]
• moment_dist::Vector{Float64}: Pitching moments around the spanwise vector of each panel. [Nm]
• moment_coeff_dist::Vector{Float64}: Pitching moment coefficient around the spanwise vector of each panel. [-]
• moment_unrefined_dist::MVector{U, Float64}: Averaged moments for unrefined sections [Nm]
• cl_unrefined_dist::MVector{U, Float64}: Averaged lift coefficients for unrefined sections [-]
• cd_unrefined_dist::MVector{U, Float64}: Averaged drag coefficients for unrefined sections [-]
• cm_unrefined_dist::MVector{U, Float64}: Averaged moment coefficients for unrefined sections [-]
• alpha_unrefined_dist::MVector{U, Float64}: Averaged angles of attack for unrefined sections [rad]
• solver_status::SolverStatus: enum, see SolverStatus