Theory
======

This page summarises the methods VANE implements. The :doc:`validation_matrix` shows
where each is checked against an analytical or reference solution.

Linearization
-------------

OpenFAST linearizes the full aero-hydro-servo-elastic system about a periodic
operating point, producing a continuous-time state-space model

.. math::

   \dot{x} = A\,x + B\,u, \qquad y = C\,x + D\,u

at one or more rotor azimuths. For a spinning rotor the matrices are
azimuth-dependent: the system is linear time-periodic, not time-invariant.

Multi-blade coordinate (MBC3) transform
---------------------------------------

The Coleman, or multi-blade coordinate, transform maps the three per-blade
degrees of freedom of a three-bladed rotor into the non-rotating frame as a
**collective**, **cosine-cyclic**, and **sine-cyclic** triplet. Averaging the
transformed matrices over a full revolution yields a single linear time-invariant
model that approximates the periodic system. The transform is applied to the
``A``, ``B``, ``C``, and ``D`` matrices; blade triplets are detected automatically
from the channel descriptions.

For an isotropic rotor the per-azimuth transformed matrices are identical, so the
averaged model is exact; anisotropy is what the azimuth-spread uncertainty
quantifies.

Eigenanalysis
-------------

Modes are the eigenpairs of the averaged state matrix. For an eigenvalue
:math:`\lambda = -\zeta\omega_n \pm i\,\omega_n\sqrt{1-\zeta^2}`:

* natural frequency :math:`\omega_n = |\lambda|`,
* damping ratio :math:`\zeta = -\mathrm{Re}(\lambda)/|\lambda|`,
* damped frequency :math:`\omega_d = \mathrm{Im}(\lambda)`.

Conjugate pairs are collapsed to a single representative (the one with positive
imaginary part). Each mode additionally reports an **eigenvalue condition number**
:math:`\kappa = 1/|y^{H}x|` (from the left and right eigenvectors) measuring its
numerical sensitivity, and a near-degeneracy flag where a repeated eigenvalue leaves
the mode shape defined only up to a subspace rotation.

Mode identification
-------------------

Each mode is labelled from the physical degrees of freedom that dominate its
participation. Blade modes are further classified as **collective**, **regressive**,
or **progressive** directly from the MBC structure (each transformed triplet is
``[collective, cosine, sine]``) and the phase-invariant whirl sign
:math:`\mathrm{Im}(q_s\,\overline{q_c})`. A Gaussian-process classifier provides an
independent, uncertainty-aware label that is fused with the rule-based one.

Cross-operating-point tracking
------------------------------

Across a sweep, modes are linked into the lines of a Campbell diagram. Rather than a
greedy adjacent-point match, VANE extracts each line as the **globally optimal
continuity path** over the whole sweep — a deterministic dynamic program over a
modal-assurance-criterion / frequency-continuity affinity. Each track carries a
confidence (its weakest link) and an ambiguity flag at crossing or veering hotspots.
See :doc:`limitations` for the precise optimality guarantee.

Uncertainty quantification
--------------------------

Every mode receives one calibrated confidence in ``[0, 1]`` combining independent
reliability factors: eigenvalue conditioning, a degeneracy penalty, an
**azimuth-stability** factor (the first-order eigenvalue perturbation of the averaged
model across the per-azimuth matrices), and the tracking confidence. A low confidence
inflates the Kalman initial covariance, propagating uncertainty into the digital-twin
export.

State-space export
------------------

The averaged or modal model is exported as a validated continuous-time system,
optionally discretised by a zero-order hold (discrete eigenvalues
:math:`e^{\lambda\,\Delta t}`), with ``Q``, ``R``, and ``P_0`` matrices built from the
per-mode confidence for a Kalman-filter-ready model.