API reference

sim!(sam, set_values; dt, total_time, vsm_interval,
     prn, lin_model, y_op)

Run a generic simulation with a matrix of control inputs. Optionally, also simulate a provided linear model.

Arguments

• sam::SymbolicAWEModel: Initialized AWE model.
• set_values::Matrix{Float64}: Control torque offsets [Nm] per step. Rows = steps, columns = winches.

Keywords

• dt: Time step [s]. Default 1/sam.set.sample_freq.
• total_time: Simulation duration [s]. Default 10.0.
• vsm_interval: Steps between VSM updates. Default 3.
• prn: Print performance summary. Default true.
• lin_model: Optional StateSpace for linear comparison.
• y_op: Operating point output vector. Required when lin_model is provided.

Returns

• (SysLog, Nothing) or (SysLog, SysLog) when lin_model is provided.

sim_reposition!(sam; dt, total_time, reposition_interval_s, target_elevation_deg,
                target_azimuth_deg, prn)

Run a simulation that periodically resets the kite's elevation and azimuth.

This function simulates the AWE model and, at a specified time interval, calls reposition! to reposition the kite to a target elevation and azimuth. It logs the entire simulation and returns a SysLog.

Arguments

• sam::SymbolicAWEModel: Initialized AWE model.

Keywords

• dt::Float64: Time step [s]. Defaults to 1/sam.set.sample_freq.
• total_time::Float64: Total simulation duration [s]. Defaults to 20.0.
• reposition_interval_s::Float64: The interval in seconds at which to reset the pose. Defaults to 5.0.
• target_elevation::Float64: The target elevation in rad for repositioning. Defaults to deg2rad(45.0).
• target_azimuth::Float64: The target azimuth in rad for repositioning. Defaults to 0.0.
• target_heading::Float64: The target heading in rad for repositioning. Defaults to 0.0.
• prn::Bool: If true, prints status messages during the simulation. Defaults to true.

Returns

• SysLog: A log of the complete simulation.

init!(sam::SymbolicAWEModel; ...)

Load or build the symbolic model, create the ODEProblem (and optionally the LinearizationProblem / control functions), serialize new builds to disk, and return a freshly initialized ODEIntegrator.

Keyword Arguments

• solver, adaptive: ODE solver and time-stepping mode. solver=nothing picks a default from sam.set.solver.
• prn: print progress messages.
• remake: force a full rebuild, ignoring any cached compiled model.
• reload: force reloading the serialized model from disk.
• outputs: vector of output variables (used by linearization / control funcs).
• create_prob, create_lin_prob, create_control_func: which artefacts to build.
• lin_vsm: linearize the VSM aerodynamics after init.
• remake_vsm: rebuild the VSM wing/aero from settings (after editing aero_geometry.yaml etc.).
• reset_vel, ignore_l0: forwarded to reinit!(sys_struct, set).
• reinit_sys: run reinit!(sys_struct, set) to refresh positions, lengths, and transforms. Set to false to preserve manual adjustments to the SystemStructure (or after calling reinit!(sys_struct, set; …) yourself).
• reset_integrator: discard the existing integrator and build a fresh one. Use when stale BDF history would taint the next run.
• vsm_min_wind=0.5: minimum |va| [m/s] for the initial VSM solve. Below this the solve is skipped and the wing's aero outputs are zeroed (the solver fails to converge / the Jacobian blows up as 1/|va|).

next_step!(s::SymbolicAWEModel, integrator::ODEIntegrator; set_values, dt, vsm_interval)

Take a simulation step, using the provided integrator.

This is a convenience method that calls the main next_step! function.

next_step!(s::SymbolicAWEModel; set_values, dt,
           vsm_interval, vsm_min_wind)

Take a simulation step forward in time.

Advances the simulation by one time step, optionally updating control inputs and re-linearizing the VSM model. Then updates the SystemStructure with the new state from the ODE integrator. Throws an error if the solver returns an unstable retcode.

Keyword Arguments

• set_values=nothing: Control input values. If nothing, current values are used.
• dt=1/s.set.sample_freq: Time step size [s].
• vsm_interval=1: Steps between VSM re-linearization. 0 disables re-linearization.
• vsm_min_wind=0.5: Minimum apparent wind [m/s] for a VSM solve. Below this the solver is skipped and the wing's aero outputs are zeroed, since the solver fails to converge or returns a Jacobian whose norm grows as 1/|va|.

find_steady_state!(s::SymbolicAWEModel, integ=s.integrator; t=1.0, dt=1/s.set.sample_freq)

Run the simulation for a short period to allow the system to settle.

During this period, the winches are braked and the wing's elevation and azimuth angles are fixed, but it is free to move radially (in distance). This allows the dynamic components of the bridle and tethers to settle into a stable, steady-state equilibrium before starting a maneuver or analysis.

Arguments

• s::SymbolicAWEModel: The model to be stabilized.
• integ: The integrator to use. Defaults to s.integrator.

Keywords

• t::Float64=1.0: The duration [s] for which to run the settling simulation.
• dt::Float64: The time step [s] for the settling simulation.

linearize!(s::SymbolicAWEModel; set_values=s.get_set_values(s.integrator)) -> LinType

Compute the full state-space linearization of the model around the current operating point.

This function uses the LinearizationProblem generated by ModelingToolkit.jl to calculate the A, B, C, and D matrices for the complete, high-order system.

Arguments

• s::SymbolicAWEModel: The model to linearize.

Keywords

• set_values: The control input vector u around which to linearize.

Returns

• LinType: A NamedTuple (A, B, C, D) containing the state-space matrices.

load_sys_struct_from_yaml(yaml_path; system_name, set, ...)

Build a SystemStructure from a component-based structural YAML file. See source for full documentation of expected blocks.

set_world_frame_damping(sys::SystemStructure, damping, point_idxs)

Set the world frame damping coefficient for specified points in the system structure.

World frame damping applies a velocity-dependent drag force in the global reference frame: $\mathbf{F}_{damp} = -c_{damp} \odot \mathbf{v}$, where $c_{damp}$ is the damping vector and $\odot$ is element-wise multiplication.

Arguments

• sys::SystemStructure: The system structure to modify.
• damping::Union{Real, AbstractVector}: Damping coefficient(s) [N·s/m]. Scalar applies same value to all 3 axes. Vector must have 3 elements for [x,y,z] damping.
• point_idxs: Indices of points to apply damping to.

Returns

• nothing

set_world_frame_damping(sys::SystemStructure, damping)

Set the world frame damping coefficient for all points in the system structure.

World frame damping applies a velocity-dependent drag force in the global reference frame: $\mathbf{F}_{damp} = -c_{damp} \odot \mathbf{v}$, where $c_{damp}$ is the damping vector and $\odot$ is element-wise multiplication.

Arguments

• sys::SystemStructure: The system structure to modify.
• damping::Union{Real, AbstractVector}: Damping coefficient(s) [N·s/m]. Scalar applies same value to all 3 axes. Vector must have 3 elements for [x,y,z] damping.

Returns

• nothing

set_body_frame_damping(sys::SystemStructure, damping, point_idxs)

Set the body frame damping coefficient for specified points in the system structure.

Arguments

• sys::SystemStructure: The system structure to modify.
• damping::Union{Real, AbstractVector}: Damping coefficient(s) [N·s/m]. Scalar applies same value to all 3 axes. Vector must have 3 elements for [x,y,z] damping.
• point_idxs: Indices of points to apply damping to.

Returns

• nothing

set_body_frame_damping(sys::SystemStructure, damping)

Set the body frame damping coefficient for all points in the system structure.

Arguments

• sys::SystemStructure: The system structure to modify.
• damping::Union{Real, AbstractVector}: Damping coefficient(s) [N·s/m]. Scalar applies same value to all 3 axes. Vector must have 3 elements for [x,y,z] damping.

Returns

• nothing

calc_steady_torque(sam::SymbolicAWEModel)

Calculates the torque for each winch that results in zero acceleration (steady state).

winch_force(s::SymbolicAWEModel)

Returns the winch force [N] for each winch.

unstretched_length(s::SymbolicAWEModel)

Returns the unstretched tether length [m] for each tether.

tether_length(s::SymbolicAWEModel)

Returns the current stretched tether length [m] for each tether.

segment_stretch_stats(sys::SystemStructure)

Calculate segment stretch statistics for segments in tension.

Returns the maximum and mean relative stretch of segments where len > l0, along with the index of the segment with maximum stretch. Relative stretch is defined as (current_length - l0) / l0. Only segments in tension (stretched) are included in the statistics.

For pulley segments, the combined length of both segments is used against the pulley's sum_l0, since the pulley constraint distributes length between them.

Arguments

• sys::SystemStructure: System structure with current segment states

Returns

• (max_stretch, mean_stretch, max_idx): Tuple of maximum stretch, mean stretch, and index of the segment with maximum stretch (or first pulley segment index)

init_module(; force=false, add_pkg=true)

Initialize the module in the current working directory.

This function performs the following actions:

• Copies all files from the module's data directory to the current working directory's data folder (pwd()/data). Existing files in the destination are NOT overwritten unless force=true.
• Copies all example scripts from the module to the current working directory's examples folder (pwd()/examples). The folder is created if it does not exist. Existing files are NOT overwritten unless force=true.
• Installs all required packages if they are not already installed. This occurs only if add_pkg=true (default). The packages are automatically determined from examples/Project.toml.

Keyword Arguments

• force::Bool=false: If true, existing files in the destination directories will be overwritten. If false (default), existing files will be preserved.
• add_pkg::Bool=true: If true (default), installs required packages if they are not already present. If false, package installation is skipped.