Data sources
============

VANE consumes the text outputs of an OpenFAST linearization analysis.

Linearization files (``.lin``)
------------------------------

The primary input is the **modern OpenFAST (ModGlue) ``.lin`` format**, written when
``Linearize = True``. Each file corresponds to one linearization time (one rotor
azimuth) and contains:

* a header with the simulation time, rotor speed, azimuth, and wind speed;
* operating-point tables for the continuous states ``x``, state derivatives
  ``xdot``, inputs ``u``, and outputs ``y``, each with a description, a
  rotating-frame flag, and a derivative order per channel;
* the state-space matrices ``A``, ``B``, ``C``, and ``D`` (absent blocks, such as
  ``B``/``D`` with zero inputs, are simply omitted).

:func:`~vane.io.lin_reader.read_lin_file` parses a file into a typed ``LinFile`` and
validates it at the trust boundary: a non-finite operating-point scalar, or a matrix
whose shape disagrees with the channel-table dimensions, is rejected with a clear
error. Fortran overflow markers (runs of ``*``) inside matrix *data* are parsed as
``nan`` with a warning rather than failing the parse.

.. note::

   The **legacy** ``.lin`` format (without the per-channel derivative-order column)
   is detected and rejected with an explicit error. Regenerate the linearization with
   a current OpenFAST release.

Model files (``.fst`` and ElastoDyn)
------------------------------------

:func:`~vane.io.fst_reader.read_fst_file` and
:func:`~vane.io.read_elastodyn_geometry` extract the linearization configuration,
active-module switches, referenced sub-files, and rotor/tower geometry from a primary
``.fst`` deck and its ElastoDyn input. These provide context (geometry, module set)
for interpreting the modes.

Azimuth sweeps and operating points
-----------------------------------

One **operating point** is a set of ``.lin`` files at the same rotor speed sampled at
several azimuths over a revolution. :func:`~vane.io.mbc_transform.mbc3_transform`
averages them into the non-rotating frame and checks the sweep is coherent: it
rejects duplicate azimuths (including the ``0``/``360`` wrap-around) and a rotor speed
that drifts across the files, since an averaged model is only meaningful for a single
periodic operating point.

A **sweep** is a series of operating points at different rotor or wind speeds; this is
what produces a Campbell diagram.

What VANE never reads or stores
-------------------------------

VANE does not require, and the repository never contains, real turbine ``.lin``,
``.outb``, or proprietary model files. Tests use synthetic data generated
programmatically; optional integration tests run only against a locally available
reference dataset and are skipped otherwise.