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 POLY POLAR_VECTORS POLAR_MATRICES INVISCID

Enumeration of the implemented aerodynamic models. See also: AeroData

Elements

• POLY: α-polynomial coefficients for cl/cd/cm (e.g. Breukels LEI coeffs, generated by the AirfoilAero package). Core only evaluates the polynomial.
• POLAR_VECTORS: Polar vectors as function of alpha (lookup tables with interpolation). A panel's table may be rewritten at run time by set_polar!, which is how a live polar source regenerates it from the panel's deformed shape each solve.
• POLAR_MATRICES: Polar matrices as function of alpha and delta (lookup tables with interpolation)
• INVISCID

LEI_AIRFOIL_BREUKELS is a deprecated alias of POLY.

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

PanelDistribution LINEAR COSINE SPLIT_PROVIDED UNCHANGED BILLOWING

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)
• BILLOWING # Split provided + sinusoidal TE billowing between ribs

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,
    Tuple{Vector{Float64}, Vector{Float64}, Vector{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
• (cl_coeffs, cd_coeffs, cm_coeffs) α-polynomial coefficients for POLY
• (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)
• billowing_percentage: TE billow as percentage of arc length (default 0.0; only used with BILLOWING distribution).
• crease_frac: Chordwise flap-hinge fraction (0–1) the polars are deflected about and the δ-deflected plate/skin is drawn with (default 0.75).
• mesh: MeshSettings — how obj_file is sliced into sections.
• airfoil: AirfoilSettings — the 2D backend and the polars it writes.

MeshSettings

How a wing's .obj mesh becomes airfoil slices, used within WingSettings: which mesh, and how to cut it.

obj_file here is the mesh the sections are generated from, an input to the geometry_file a wing then flies. That is not the wing's own obj_file, which is an alternative to geometry_file — a wing built straight from an obj and a dat, with no polar generation in between — and which cannot be given alongside one.

Apart from n_sections, which obj_to_yaml requires, every default here is the one that call and ShrinkWrap already apply, so a wing naming no mesh: block slices as an unconfigured call.

Fields

• obj_file: Mesh the sections are sliced from, relative to the data directory (default "", no mesh).
• n_sections: Sections sliced from the mesh (default 45).
• n_bins: Leading-edge stations marched across the span; more gives a smoother trace (default 60).
• rotation: Rows of the mesh-to-slicer rotation, which brings the mesh into the slicer's convention of x = chord, y = span, z = up (default the identity).
• wingtip_distance: Spanwise length [m] the outermost sections stop short of each tip (default 0.0).
• clearance: Shrink-wrap offset [chord fraction] the contour holds outside every cloud point, and the radius its convex corners are rounded at (default 0.006).
• min_concave_radius: Shrink-wrap rolling-ball radius [chord fraction], bridging gaps and crevices in the point cloud (default 0.02).

AirfoilSettings

The 2D section backend and the polars it tabulates, used within WingSettings. One block answers for both the tables a mesh is sliced into and the live polars a deformed section is re-solved on, so the two cannot be generated at different transition settings or off different networks.

Fields

• solver: Section backend, "neuralfoil" or "xfoil" (default "neuralfoil").
• model_size: NeuralFoil network size (default "large").
• n_crit: e^N transition criticality; lower is dirtier, so transition is earlier (default 9.0, the standard clean-tunnel value).
• xtr_upper / xtr_lower: Forced transition as a chord fraction, applied to whichever backend solver names (default 0.05).
• alpha_range: Angle-of-attack sweep [deg] as [first, step, last] (default [-180, 1, 180]).
• delta_range: Flap-deflection sweep [deg] as [first, step, last]; nothing for a dataset generated without a flap sweep (default nothing).
• live_offsets: Angles [deg] off the reference angle a live polar is sampled at (default -12:3:12).
• va: apparent wind speed [m/s] the polars' Reynolds number is taken at (default 25.0).
• chord_ref: Reference (maximum panel) chord [m], which Reynolds is defined against (default 1.0).
• table_format: Per-node table format, :csv (readable) or :arrow (about ten times faster to load; default :arrow). Written in YAML as a plain string, and carried as the Symbol the generator takes.

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^3) (default 1.225)
• max_iterations: Maximum solver iterations (default 1500)
• rtol: Relative tolerance on the fixed-point residual (default 1e-5)
• tol_reference_error: Reference error tolerance (default 0.001)
• relaxation_factor: Convergence relaxation factor (default 0.03)
• is_with_artificial_viscosity: Enable Li/Gaunaa post-stall artificial viscosity (default false)
• artificial_viscosity_factor: Viscosity scaling coefficient k (default 0.035)
• type_initial_gamma_distribution: ELLIPTIC or ZEROS (default ZEROS)
• use_gamma_prev: Reuse provided previous gamma as initial guess when available (default true)
• core_radius_fraction: Bound vortex core cut-off, as a fraction of the filament length, following Damiani et al. (2019) (default 0.05)
• mu: Dynamic viscosity (N*s/m^2) (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)
• flow_curvature: Add the thin-airfoil pitch-rate moment increment to each section (default false)
• is_with_viscous_drag_correction: Add the spanwise-flow viscous drag and side force to each section (default false)
• is_with_attached_trailed_force: Add the force on the chordwise trailed vortex segments bound to each panel (default false)

mutable struct Section{T}

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

Fields

• LE_point::MVector{3, T}: Leading edge point coordinates
• TE_point::MVector{3, T}: Trailing edge point coordinates
• aero_model::AeroModel: AeroModel
• aero_data::AeroData: See: AeroData
• section_aero::Union{Nothing, SectionAero}: optional surface aero table, see SectionAero

Section(LE_point, TE_point, 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::AbstractVector{<:Section}: Vector of wing sections, see: Section
• refined_sections::AbstractVector{<: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
• crease_frac::Float64: chordwise flap-hinge fraction (0–1) used when plotting the deflected plate

Deformation Fields (optional, for deformable wings)

• non_deformed_sections::AbstractVector{<: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

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,
     billowing_percentage::Float64=0.0)

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: Whether to remove the NaNs from interpolations or not
• use_prior_polar::Bool: Reuse prior refined/panel polar mapping during geometry-only updates
• billowing_percentage::Float64: TE billow as percentage of arc length (0=flat)

ObjWing(obj_path[, dat_path]; n_panels, Re, alpha_range, delta_range,
        n_sections, spanwise_direction, aero_solver, remake, output_dir,
        crease_frac, verbose) → Wing

Convenience constructor retained for backward compatibility. Converts an OBJ mesh to a YAML wing geometry via ObjAdapter.obj_to_yaml and returns a Wing.

dat_path is accepted but ignored — airfoil shapes are extracted directly from the OBJ geometry. Use aero_solver=AirfoilAero.XFoilSolver() to reproduce old XFoil-based polars; the default is AirfoilAero.NeuralFoilSolver().

alpha_range and delta_range are in degrees (matching ObjAdapter.obj_to_yaml).

By default (remake=false) an existing geometry.yaml in output_dir is reused, skipping the expensive polar generation. Set remake=true to force regeneration.

@with_kw mutable struct BodyAerodynamics{P,W<:AbstractWing}

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

Fields

• panels::Vector{<:Panel}: Vector of refined Panel structs
• wings::Vector{W}: A vector of wings of type W <: AbstractWing; a body can have multiple wings
• va_vec::MVec3 = zeros(MVec3): apparent wind vector [m/s], see: MVec3
• omega::MVec3 = zeros(MVec3): A vector of the turn rates around the KA body axes
• reference_point::MVec3 = zeros(MVec3): The point omega turns the body about [m]
• 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_rel_dist::MVector{P, Float64} = zeros(Float64, P): norm of the relative velocity crossed with the panel spanwise axis, |vrel × yairf| [m/s]
• pitch_rate_dist::MVector{P, Float64} = zeros(Float64, P): rotation rate of each panel about its own spanwise axis, positive nose-up [rad/s]; set by set_va! and read when the solver has flow_curvature enabled
• work_vectors::NTuple{10, MVec3} = ntuple(_ -> zeros(MVec3), 10)
• AIC::Array{Float64, 3} = zeros(P, P, 3): control-point influence coefficients, the matrix the circulation is solved against; component last so that each AIC[:, :, k] slice is a contiguous BLAS matrix
• AIC_aero_center::Array{Float64, 3} = zeros(P, P, 3): aerodynamic-centre (LLT) influence coefficients, used only for the corrected angle of attack
• projected_area::Float64 = 1.0: The area projected onto the xy-plane of the KA body frame [m²]
• c_ref::Float64 = 1.0: Reference chord length (max panel chord) [m]
• cache::Vector{PreallocationTools.LazyBufferCache{typeof(identity), typeof(identity)}} = [LazyBufferCache() for _ in 1:12]

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 tolerance on the fixed-point residual
• tol_reference_error::Float64 = 0.001
• relaxation_factor::Float64 = 0.03: Relaxation factor for convergence

Artificial viscosity settings

• is_with_artificial_viscosity::Bool = false: Enable the Li/Gaunaa spanwise artificial viscosity (TORQUE 2026) for post-stall stabilization in the LOOP solver
• artificial_viscosity_factor::Float64 = 0.035: Coefficient k in the viscosity scaling (the conservative envelope from the paper)

Additional settings

• type_initial_gamma_distribution::InitialGammaDistribution = ZEROS: see: InitialGammaDistribution
• use_gamma_prev::Bool = true: reuse provided previous gamma as initial guess when available
• core_radius_fraction::Float64 = 0.05: Bound vortex core cut-off, as a fraction of the filament length, following Damiani et al. (2019)
• 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
• flow_curvature::Bool = false: Add the thin-airfoil pitch-rate moment increment -(π/4) q̂ to each section, see: flow_curvature_cm
• is_with_viscous_drag_correction::Bool = false: Add the spanwise-flow viscous drag and side force to each section, see: spanwise_flow_drag
• is_with_attached_trailed_force::Bool = false: Add the force on the chordwise trailed vortex segments bound to each panel, see: attached_trailed_loads
• 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 per unit span of the panels [N/m]
• drag_dist::Vector{Float64}: Drag force per unit span of the panels [N/m]
• panelmomentdist::Vector{Float64}: Pitching moment per unit span about y_airf [Nm/m]
• 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 the KA 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 airfoil moment coefficients for unrefined sections [-]
• moment_coeff_unrefined_dist::MVector{U, Float64}: Summed moment_frac-referenced pitching-moment coefficient per unrefined section [-]
• alpha_unrefined_dist::MVector{U, Float64}: Averaged angles of attack for unrefined sections [rad]
• solver_status::SolverStatus: enum, see SolverStatus

SolveFailure(msg)

Thrown by solve!(...; throw_on_fail=true) when the circulation loop missed the solver's tolerances, or when the coefficients it assembled are not finite.