API contract
============

This page states the guarantees VANE's public entry points make, independent of their
implementation. They hold for the documented public API; private helpers may change
without notice.

General guarantees
------------------

**Determinism.**
   Given the same inputs, every analysis function returns identical results. There are
   no random restarts, hidden global state, or wall-clock dependence. Stochastic
   utilities (the benchmark noise sweep, synthetic training data) are explicitly
   seeded.

**Validation at the boundary.**
   Inputs are validated where they enter the library and rejected with a specific,
   typed exception and a clear message, rather than surfacing as an opaque lower-level
   error. Numerical results are never silently produced from malformed input.

**Typed and documented.**
   Every public function has complete type annotations and a NumPy-style docstring
   stating its parameters, returns, and the conditions under which it raises.

Entry-point guarantees
----------------------

``read_lin_file``
   Returns a ``LinFile`` only for a well-formed modern ``.lin`` file. Raises
   ``LinFileFormatError`` for an empty, truncated, legacy, or structurally invalid
   file; for a non-finite operating-point scalar; or for an ``A``/``B``/``C``/``D``
   matrix whose shape disagrees with the channel-table dimensions. Overflow markers in
   matrix data become ``nan``.

``mbc3_transform``
   Requires one coherent operating point: a non-empty set of azimuth files with
   consistent channel layout, distinct azimuths (including the wrap-around), and a
   rotor speed that does not drift. Violations raise ``ValueError``. The result is the
   azimuth-averaged non-rotating model; with ``retain_per_azimuth=True`` it also keeps
   the per-azimuth matrices.

``compute_modes`` / ``modes_from_mbc``
   Raise ``ValueError`` for a non-finite state matrix. Return conjugate-collapsed
   modes (positive-imaginary representatives) with frequencies, damping, phase-
   normalised shapes, condition numbers, degeneracy flags, and unstable/over-damped
   counts.

``identify_modes``
   Rejects a ``frequency_weight``, ``mac_threshold``, or ``ambiguity_margin`` outside
   ``[0, 1]`` (NaN included) and inconsistent mode-shape layouts. Returns
   deterministic tracks, each with a confidence and an ambiguity flag.

``excitation_frequencies`` / ``find_resonances``
   Reject non-positive, fractional, non-finite, or duplicate harmonics; an empty
   harmonic set is a valid no-op. ``find_resonances`` requires a rotor-speed (rpm)
   Campbell diagram.

``ModalPipeline``
   Validates its tuning weights and harmonics at construction, and rejects an empty
   operating-point set, an unknown parameter name, or non-finite/duplicate
   operating-parameter values at ``run``. Operating points are sorted by the
   operating parameter, so input order does not affect the result.

``state_space`` / ``modal_state_space``
   Export a dimension-checked LTI system. A modal realisation re-extracts to the same
   frequencies and damping it encodes (export fidelity).

``modes_table`` / ``campbell_table`` / ``write_table``
   Reject length mismatches between a solution and its optional label/confidence/
   spread inputs, a Campbell parameter name colliding with a reserved column, and an
   unsupported file suffix.

``discover_operating_points``
   Groups a directory's ``<case>.<n>.lin`` files into named
   ``DiscoveredOperatingPoint`` objects (one per ``<case>`` root, ordered by case);
   each behaves as a sequence of its ``LinFile`` objects. Raises ``FileNotFoundError``
   when the directory contains no ``.lin`` files. Accepts a ``str`` or ``Path``.

``run_study``
   Validates ``parameter_name`` first, then runs the pipeline and returns a
   ``StudyResult`` carrying the ``PipelineResult`` and a ``Provenance`` record.
   Operating points are sorted deterministically by the operating parameter, and the
   recorded provenance is in that same sorted order (so it lines up with the Campbell
   result).

``Provenance`` / ``StudyResult.write_bundle``
   The provenance records the library version, a timestamp (the UTC time of the run by
   default; a caller-injected ``timestamp`` is recorded as provided), the tuning
   thresholds and pipeline-normalized harmonics, an ``environment`` block (Python,
   platform, and
   scientific-dependency versions), and, per operating point, the case name, full
   azimuth list, averaged rotor/wind speed, operating-parameter value, and that
   point's own SHA-256-hashed source files. ``write_bundle`` writes ``provenance.json``
   (the manifest) and ``campbell.csv`` to a directory it creates, accepting a ``str``
   or ``Path``.

Exceptions
----------

* ``LinFileFormatError`` (a ``ValueError`` subclass) — malformed linearization input.
* ``ValueError`` — invalid arguments or incoherent inputs to an analysis function.
* ``IndexError`` — out-of-range operating-point or mode indices.

Stability
---------

During the ``0.y.z`` alpha series the public API may change between minor versions;
such changes are recorded in the :doc:`../user_guide/changelog`. Once the API
stabilises at ``1.0.0``, breaking changes follow semantic versioning.