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 Changelog. Once the API stabilises at 1.0.0, breaking changes follow semantic versioning.