API reference

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

Run a generic simulation for a given AWE model and a matrix of control inputs. Optionally, also simulate a provided linear model, returning both logs.

Arguments

• sam::SymbolicAWEModel: Initialized AWE model.
• set_values::Matrix{Float64}: A matrix of external control torques [Nm] to be applied at each time step. The number of rows must equal the number of simulation steps, and the number of columns must equal the number of winches.

Keywords

• dt::Float64: Time step [s]. Defaults to 1/sam.set.sample_freq.
• total_time::Float64: Total simulation duration [s]. Defaults to 10.0.
• vsm_interval::Int: Interval for the value state machine updates. Defaults to 3.
• prn::Bool: If true, prints a performance summary upon completion. Defaults to true.
• lin_model: (optional) a continuous-time StateSpace object from ControlSystemsBase. If provided, the linear model is simulated in parallel and a second log is returned.

Returns

• If lin_model is not provided: (SysLog, Nothing) (nonlinear log, nothing)
• If lin_model is provided: (SysLog, SysLog) (nonlinear, linear logs)

sim_oscillate!(sam; dt, total_time, steering_freq, steering_magnitude, vsm_interval,
               bias, prn, lin_model)

Run a simulation with oscillating steering input on the given AWE model. Optionally also simulate a provided linear model.

Keywords (see sim!)

• lin_model: (optional) a continuous-time StateSpace object from ControlSystemsBase.

Returns

• If lin_model is not provided: (SysLog, Nothing) (nonlinear log, nothing)
• If lin_model is provided: (SysLog, SysLog) (nonlinear, linear logs)

sim_turn!(sam; dt, total_time, steering_time, steering_magnitude, vsm_interval, prn,
          lin_model)

Run a simulation with a constant steering input for a specified duration. Optionally also simulate a provided linear model.

Keywords (see sim!)

• lin_model: (optional) a continuous-time StateSpace object from ControlSystemsBase.

Returns

• If lin_model is not provided: (SysLog, Nothing) (nonlinear log, nothing)
• If lin_model is provided: (SysLog, SysLog) (nonlinear, linear logs)

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

Initialize the SymbolicAWEModel.

This is the main entry point for setting up the model. It handles:

• Loading or building the symbolic model (full_sys).
• Creating the ODEProblem, LinearizationProblem, and control functions as needed.
• Serializing the model to disk if it was newly built.
• Initializing the ODE integrator.

Keyword Arguments

• solver: The ODE solver to use. If nothing, a default is chosen based on settings.
• adaptive::Bool: Enable adaptive time-stepping for the solver.
• prn::Bool: Enable printing of progress messages.
• remake::Bool: Force a full rebuild of the symbolic model, ignoring any cached versions.
• reload::Bool: Force reloading of the serialized model from disk.
• outputs: A vector of variables to be treated as system outputs.
• create_prob::Bool: Whether to create the ODEProblem.
• create_lin_prob::Bool: Whether to create the LinearizationProblem.
• create_control_func::Bool: Whether to generate the control functions.
• lin_vsm::Bool: Whether to linearize the aerodynamics using the Vortex Step Method (VSM) after initialization.
• remake_vsm::Bool: Recreate VSM wing and aerodynamics from settings (useful after modifying aero_geometry.yaml or other VSM settings).

Returns

• The initialized ODEIntegrator.

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)

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.

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.

simple_linearize!(s::SymbolicAWEModel; tstab=10.0) -> LinType

Compute a simplified, low-order state-space model by numerically linearizing the full simulation.

This function performs system identification by perturbing the states and inputs of the full nonlinear model and observing the effect on the state derivatives and outputs. It runs the simulation for a short duration (tstab) after each perturbation to find the steady-state response.

Arguments

• s::SymbolicAWEModel: The model to linearize.

Keywords

• tstab::Float64=10.0: The simulation time [s] to run after each perturbation to reach a steady state.

Returns

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

    load_sys_struct_from_yaml(yaml_path::AbstractString; system_name="from_yaml", set=nothing)

Build a SystemStructure from a component-based structural YAML file.

IMPORTANT: All indices (points, segments, etc.) must be sequential starting from 1 with no gaps.

Expected top-level blocks

• points: table with headers [id,x,y,z,type,mass,body_damping,world_damping]

  • type: STATIC, DYNAMIC, WING, or QUASI_STATIC
  • id must be sequential: 1, 2, 3, ...

• segments: table with one of two formats:

  • Direct format: [id,point_i,point_j,type,l0,diameter_mm,unit_stiffness,unit_damping,compression_frac]
  • Named format: [name,point_i,point_j] (requires segment_properties block)

• segment_properties: (optional) table with headers [name,type,l0,diameter_mm,unit_stiffness,unit_damping,compression_frac]

  • Used with named segment format for shared properties across symmetric segments

• pulleys: table with headers [id,segment_i,segment_j,type]

  • type: DYNAMIC or QUASI_STATIC

• groups: (optional) table with headers [id,point_idxs,gamma,type,reference_chord_frac]

• tethers: (optional) table with headers [id,segment_ids,ground_point_id]

• winches: (optional) table with headers [id,tether_ids]

• wings: (optional, typically from VSM configuration)

• transforms: (optional, typically from settings)

update_sys_struct_from_yaml!(sys_struct::SystemStructure,
                              struc_yaml::AbstractString)

Update an existing SystemStructure in-place from a (possibly modified) structural geometry YAML file. Inverse of update_yaml_from_sys_struct!.

Updates pos_cad for points and l0 for segments, matched by symbolic name. When l0 is nothing in the YAML, it is auto-calculated from the endpoint pos_cad positions.

Only raw geometry is updated. Call reinit!(sys_struct, set) afterward to recompute derived quantities (pos_b, pos_w, wing frames, etc.).

Unmatched names are silently skipped (the YAML may contain a subset of components).

Arguments

• sys_struct: The SystemStructure to update in-place.
• struc_yaml: Path to the structural geometry YAML file.

Example

sys = load_sys_struct_from_yaml("struc_geometry.yaml"; ...)
# ... edit YAML externally ...
update_sys_struct_from_yaml!(sys, "struc_geometry.yaml")

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

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.