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.

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 alpha series (pre-``0.1.0``) the public API may change between minor
versions; such changes are recorded in the :doc:`../user_guide/changelog`. From the
first tagged release, breaking changes follow semantic versioning.