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 Changelog. From the first tagged release, breaking changes follow semantic versioning.