Coordinate systems, origins & datums
====================================

This page records the frames, orderings, and reference points VANE assumes, so that
results can be interpreted unambiguously.

Reference frames
----------------

Rotating (blade) frame
   The frame OpenFAST writes for blade degrees of freedom, rotating with the rotor.
   Channels carry a per-channel *rotating-frame* flag in the ``.lin`` tables; this is
   the hook the MBC3 transform uses to find blade triplets.

Non-rotating (fixed) frame
   The frame after the MBC3 transform. The three per-blade coordinates of a triplet
   become a non-rotating ``[collective, cosine, sine]`` set. The averaged model lives
   entirely in this frame; tower, drivetrain, and platform degrees of freedom are
   already non-rotating and pass through unchanged.

Azimuth convention
------------------

Rotor azimuth is read from the ``.lin`` header in radians and wrapped to ``[0, 360)``
degrees internally for sweep-coherence checks. The MBC3 transform integrates over a
full revolution; the averaged model is independent of the azimuth origin for an
isotropic rotor.

State-space layout
------------------

After the transform, the state vector is reordered into the canonical block layout

.. code-block:: text

   x = [ q2 ; q2dot ; q1 ]

where ``q2`` are the second-order (displacement) degrees of freedom, ``q2dot`` their
time derivatives, and ``q1`` the first-order states. Mode shapes are reported over the
displacement block (``q2``); the eigensolver reduces the full eigenvectors to those
rows. Multi-blade coordinate annotations
(``MBCResult.mbc_coordinates`` →
``ModalSolution.dof_mbc_coordinates``) record, for each state, whether it is a
collective, cosine, or sine coordinate.

Degree-of-freedom mapping
-------------------------

Each channel description embeds an OpenFAST internal DOF token (for example
``DOF_TFA1`` for the first tower fore-aft mode or ``DOF_BF(1,1)`` for blade 1's first
flapwise mode). :func:`~vane.config.classify_dof` maps that token onto a physical DOF
category, originating module, and blade index, which drives labelling and the blade
collective/regressive/progressive taxonomy.

Origins and datums
------------------

VANE does not re-define geometric origins; it inherits OpenFAST's. Rotor/tower
geometry extracted from the ElastoDyn input (hub height, tower stations, blade
length) is reported in the model's own datum for context only and is not used to
re-reference the state-space model.