Units & conventions
===================

VANE follows OpenFAST's SI conventions on input and is explicit about the units it
reports.

Quantities and units
--------------------

.. list-table::
   :header-rows: 1
   :widths: 30 20 50

   * - Quantity
     - Unit
     - Notes
   * - Rotor speed (input)
     - rad/s
     - As written in the ``.lin`` header (``rotor_speed``).
   * - Rotor speed (reported)
     - rev/min
     - Campbell parameter ``rotor_speed_rpm`` = rad/s × 30/π.
   * - Azimuth
     - rad (input)
     - Wrapped to ``[0, 360)`` deg internally for sweep checks.
   * - Natural / damped frequency
     - Hz
     - ``natural_frequencies_hz``, ``damped_frequencies_hz``.
   * - Angular frequency
     - rad/s
     - Used in theory expressions; ``ω = 2π f``.
   * - Damping ratio
     - dimensionless
     - ``ζ`` in ``[0, 1)`` for an underdamped mode.
   * - Wind speed
     - m/s
     - Mean hub-height; ``0`` when InflowWind is absent.
   * - Excitation harmonic
     - integer
     - The ``nP`` line, ``n × rpm / 60`` Hz; ``n`` a positive integer.

Sign and normalisation conventions
-----------------------------------

* **Eigenvalues**: the conjugate representative with positive imaginary part is kept.
* **Damping**: ``ζ = -Re(λ)/|λ|``; positive for a stable (decaying) mode. The
  solution separately counts unstable (positive-real-part) and over-damped (stable
  real) eigenvalues.
* **Mode shapes**: complex, phase-normalised so the dominant component is real and
  positive; correlations (MAC) are invariant to per-mode complex scaling, so the
  normalisation does not affect identification.
* **Whirl direction**: for the cyclic pair of a blade triplet,
  ``Im(q_s · conj(q_c)) > 0`` is **regressive** (the lower-frequency ``w0 - Omega``
  line) and ``< 0`` is **progressive**, calibrated against the Coleman split (see
  :doc:`theory`).

Confidence and uncertainty
--------------------------

Per-mode confidence is a dimensionless value in ``[0, 1]`` (1 = fully trusted). The
azimuth-spread standard deviations are reported in the same units as the underlying
quantity (Hz for frequency, dimensionless for damping).

Tabular export
--------------

:mod:`vane.export` writes the modal and Campbell tables with the column names and
units above; the operating-parameter column is named after the diagram's parameter
(``rotor_speed_rpm`` or ``wind_speed``).