Quickstart
==========

The high-level :class:`~vane.ModalPipeline` runs the whole workflow — MBC3 transform,
eigenanalysis, cross-operating-point tracking, Campbell assembly, and resonance
detection — over a set of operating points.

End-to-end pipeline
-------------------

.. code-block:: python

   from vane import ModalPipeline
   from vane.io.lin_reader import read_lin_file

   # Each operating point is one azimuth sweep: a list of .lin files at the same
   # rotor speed but different azimuths.
   operating_points = [
       [read_lin_file(p) for p in azimuth_files]
       for azimuth_files in sweep        # your grouping of .lin files
   ]

   result = ModalPipeline().run(operating_points)

   for track in result.campbell.tracks:
       print(track.label.label, track.natural_frequencies_hz)

   for crossing in result.resonances:
       print(f"{crossing.harmonic}P at {crossing.rotor_speed_rpm:.1f} rpm")

   system = result.state_space(0)        # A, B, C, D at the first operating point

Grouping ``.lin`` files
-----------------------

OpenFAST writes one ``.lin`` file per linearization time, named
``<case>.<n>.lin``. Files sharing a ``<case>`` root form one operating point's
azimuth sweep. The ``examples/`` scripts show a directory-based grouping; the
pipeline sorts operating points by the operating parameter internally, so input
order does not matter.

Lower-level building blocks
---------------------------

Every stage is also available directly:

.. code-block:: python

   from vane.io.mbc_transform import mbc3_transform
   from vane.modal.eigensolver import modes_from_mbc
   from vane.modal.identifier import identify_modes
   from vane.campbell.builder import build_campbell

   mbc = mbc3_transform(azimuth_files)             # non-rotating averaged model
   solution = modes_from_mbc(mbc)                  # frequencies, damping, shapes
   tracks = identify_modes([solution_a, solution_b])  # cross-operating-point tracks
   diagram = build_campbell(tracks, rotor_speeds)

Reproducible studies
--------------------

For a campaign of linearization files on disk, the study API discovers and groups the
files, runs the pipeline, and records **provenance** — the exact source files (with
content hashes), the azimuth coverage of each operating point, the tuning thresholds,
and the library version — so a result can be tied back to precisely the inputs and
assumptions that produced it:

.. code-block:: python

   from vane import discover_operating_points, run_study

   operating_points = discover_operating_points("path/to/lin_files")
   study = run_study(operating_points)

   print(study.provenance.vane_version, study.provenance.source_files)
   study.write_bundle("study_output")   # provenance.json + campbell.csv

Data-free demonstration
-----------------------

To see the analysis path without OpenFAST data, run the synthetic quickstart, which
builds a system with known modes, extracts and labels them, attaches a unified
confidence, writes a CSV, and reports recovery accuracy and noise robustness:

.. code-block:: bash

   python examples/synthetic_quickstart.py

See :doc:`../reference/api_reference` for the full API and
:doc:`../reference/api_contract` for the guarantees each entry point makes.