API reference 

monopile_geometry(*, hub_height=90.0, tower_base_z=20.0, blade_length=60.0, monopile_radius=3.0, water_depth=20.0, embedment=25.0, mudline_z=0.0, n_blades=3, shaft_tilt_deg=-5.0, precone_deg=-2.5, overhang=7.0)[source]

Build a bottom-fixed monopile reference geometry (no mooring lines).

The monopile runs from below the mudline up to the tower base above the waterline. There are no mooring lines; the platform reference point sits at the mudline, so platform degrees of freedom (if any) act there.

Parameters:

mudline_z (float, optional) – Seabed elevation. The default 0.0 keeps the plain bottom-fixed convention (seabed at the reference plane, no water column). Offshore presets pass -water_depth so the still-water plane at z = 0 sits above the seabed and the pile crosses the waterline.
hub_height (float)
tower_base_z (float)
blade_length (float)
monopile_radius (float)
water_depth (float)
embedment (float)
n_blades (int)
shaft_tilt_deg (float)
precone_deg (float)
overhang (float)

Returns:

FowtGeometry – The assembled monopile geometry.

Return type:

onshore_geometry(*, hub_height=90.0, blade_length=60.0, foundation_radius=8.0, n_blades=3, shaft_tilt_deg=-5.0, precone_deg=-2.5, overhang=7.0)[source]

Build a land-based (onshore) reference geometry: tower + rotor on the ground.

The tower rises from the ground plane (z = 0) to the hub; there is no substructure, water, or mooring. A foundation ring marks the base.

Returns:

FowtGeometry – The assembled onshore geometry.

Parameters:

hub_height (float)
blade_length (float)
foundation_radius (float)
n_blades (int)
shaft_tilt_deg (float)
precone_deg (float)
overhang (float)

Return type:

semisub_geometry(*, hub_height=90.0, tower_base_z=10.0, blade_length=60.0, column_radius=6.0, offset_radius=28.0, draft=20.0, freeboard=10.0, fairlead_radius=28.0, fairlead_depth=14.0, anchor_radius=420.0, water_depth=200.0, n_blades=3, shaft_tilt_deg=-5.0, precone_deg=-2.5, overhang=7.0)[source]

Build a three-column semi-submersible FOWT reference geometry.

A central column carries the tower; three outer columns on an offset radius are joined to it by pontoons and braces, and three catenary mooring lines run from the outer-column fairleads to seabed anchors. Defaults are representative of a 5-MW-class semi-submersible and may be overridden per turbine.

Parameters:

hub_height (float, optional) – Hub height above SWL.
tower_base_z (float, optional) – Tower-base height above SWL (top of the central column / freeboard).
blade_length (float, optional) – Blade length from root to tip.
column_radius (float, optional) – Radius of each buoyancy column.
offset_radius (float, optional) – Radial distance of the outer columns from the centreline.
draft (float, optional) – Column draft below SWL.
freeboard (float, optional) – Column height above SWL.
fairlead_radius (float, optional) – Radius of the mooring fairleads.
fairlead_depth (float, optional) – Depth of the fairleads below SWL.
anchor_radius (float, optional) – Radius of the seabed anchors.
water_depth (float, optional) – Water depth (anchors sit on the seabed at -water_depth).
n_blades (int, optional) – Number of rotor blades.
shaft_tilt_deg (float, optional) – Shaft tilt angle in degrees, with the OpenFAST ShftTilt sign (positive raises the downwind shaft end). The default -5 tilts the upwind rotor nose-up, as for the NREL 5-MW turbine.
precone_deg (float, optional) – Blade precone angle in degrees, with the OpenFAST PreCone sign (positive cones the blades downwind). The default -2.5 cones the blades upwind, away from the tower.
overhang (float, optional) – Upwind shaft overhang of the hub from the tower top.

Returns:

FowtGeometry – The assembled semi-submersible geometry.

Return type:

spar_geometry(*, hub_height=90.0, tower_base_z=10.0, blade_length=60.0, spar_radius=4.7, draft=120.0, fairlead_radius=5.2, fairlead_depth=70.0, anchor_radius=850.0, water_depth=320.0, n_blades=3, shaft_tilt_deg=-5.0, precone_deg=-2.5, overhang=7.0)[source]

Build a single-column spar-buoy FOWT reference geometry (OC3-Hywind class).

A deep slender cylinder provides buoyancy and ballast stability; three catenary mooring lines spread from fairleads near the waterline. Parameters mirror semisub_geometry().

Returns:

FowtGeometry – The assembled spar geometry.

Parameters:

hub_height (float)
tower_base_z (float)
blade_length (float)
spar_radius (float)
draft (float)
fairlead_radius (float)
fairlead_depth (float)
anchor_radius (float)
water_depth (float)
n_blades (int)
shaft_tilt_deg (float)
precone_deg (float)
overhang (float)

Return type:

tlp_geometry(*, hub_height=90.0, tower_base_z=10.0, blade_length=60.0, column_radius=6.0, pontoon_radius=20.0, draft=20.0, freeboard=10.0, water_depth=200.0, n_tendons=3, n_blades=3, shaft_tilt_deg=-5.0, precone_deg=-2.5, overhang=7.0)[source]

Build a tension-leg-platform (TLP) reference geometry.

A central buoyancy column carries the tower; spoke pontoons reach out to the tendon-attachment corners, and vertical taut tendons run straight down from each corner to a seabed anchor directly below it — the defining TLP feature, unlike a semi-submersible’s spread catenary mooring.

Returns:

FowtGeometry – The assembled TLP geometry.

Parameters:

hub_height (float)
tower_base_z (float)
blade_length (float)
column_radius (float)
pontoon_radius (float)
draft (float)
freeboard (float)
water_depth (float)
n_tendons (int)
n_blades (int)
shaft_tilt_deg (float)
precone_deg (float)
overhang (float)

Return type:

BiorthogonalParticipation

Modal analysis

Modal analysis — eigensolver, MAC, participation factors, mode identification.

Given the non-rotating (MBC-averaged) state matrix \(A\) in the canonical [q2, q2dot, q1] layout, an eigenvalue analysis yields the full-system modes: their natural frequencies, damping ratios, and (complex) mode shapes.

Each under-damped mode appears as a complex-conjugate eigenvalue pair; only the representative with positive imaginary part is retained. For an eigenvalue \(\lambda\), the modal quantities are

\[\omega_n = |\lambda|, \qquad \zeta = \frac{-\operatorname{Re}\lambda}{|\lambda|}, \qquad \omega_d = \operatorname{Im}\lambda,\]

so the natural and damped frequencies in hertz are \(\omega_n / 2\pi\) and \(\omega_d / 2\pi\). The velocity (q2dot) rows are dropped from the returned mode shapes, leaving the second-order displacements and first-order states; the full eigenvectors are also retained.

Notes

OpenFAST exposes no full-system mass or stiffness matrix, so modal frequencies are obtained directly from \(A\) and vary with operating point.

Numerically split rigid-body pairs. A degree of freedom without restoring stiffness – the free rotor-azimuth (generator) DOF of a variable-speed turbine – contributes a zero eigenvalue (the azimuth integrator) next to a small real one (the aerodynamic damping of the rotor speed). Where the damping is small, the finite-difference noise in the azimuth column of \(A\) is enough to merge the two into a complex pair of negligible frequency (periods of tens of minutes) instead of two real eigenvalues. Such a pair is not an oscillation, and reporting it as one makes a spurious mode appear at isolated operating points. A complex pair is therefore classified as a split rigid-body pair – dropped from the oscillatory modes and counted in n_rigid_body_modes – when both

its natural frequency is below rigid_body_frequency_hz (default RIGID_BODY_FREQUENCY_HZ, a period of 333 s: well below every restoring-force mode of a wind turbine, including the 100-200 s surge and sway of moored floating platforms), and
its imaginary part is not resolved by the data: by first-order perturbation theory a relative error \(\delta\) in \(A\) moves the eigenvalue by up to \(\kappa\,\delta\,\rho(A)\), so a pair with

\[|\operatorname{Im}\lambda| \le \delta\,\kappa(\lambda)\,\rho(A)\]

is indistinguishable from two real eigenvalues. \(\kappa\) is evaluated on the diagonally balanced matrix (the problem the eigenvalue solver actually solves, and independent of the state units), \(\rho\) is the spectral radius and \(\delta\) is split_pair_rtol (default SPLIT_PAIR_RTOL).

Both conditions are needed. The first alone would drop a well-resolved slow oscillation of an unusually soft model. The second alone is not enough because the spectral radius of a model with stiff first-order states (MoorDyn line nodes) is large, so well-resolved surge and sway modes of such a model can fall below the bound; the frequency floor keeps them.

RIGID_BODY_FREQUENCY_HZ = 0.003

Natural frequency (Hz) below which a numerically split pair may be rigid-body.

A period of 333 s. Moored floating platforms have their slowest restoring-force modes (surge, sway) at periods of roughly 100-200 s (0.005-0.01 Hz), so no physical oscillation of a wind turbine is this slow.

SPLIT_PAIR_RTOL = 0.0001

Relative accuracy \(\delta\) of the state matrix assumed for split pairs.

OpenFAST computes its Jacobians by finite differences with perturbations of order \(10^{-3}\), and the MBC transform averages them over azimuth, so the entries of \(A\) are not reliable to better than about this relative level. On the reference-turbine sweeps the split rigid-body pairs sit 10-200 times inside the resulting bound, and the platform modes of floating models without MoorDyn 2-50 times outside it.

class ModalSolution(eigenvalues, natural_frequencies_hz, damping_ratios, damped_frequencies_hz, mode_shapes, full_eigenvectors, n_rigid_body_modes, dof_descriptions, condition_numbers=<factory>, is_degenerate=<factory>, n_unstable=0, n_overdamped=0, dof_mbc_coordinates=<factory>, full_left_eigenvectors=<factory>, state_descriptions=<factory>, n_split_rigid_body_pairs=0, rotor_speed_rpm=nan)[source]

Bases: object

Modal properties extracted from a state matrix.

All per-mode arrays share the same ordering (ascending natural frequency when the solver sorts). Only under-damped modes (positive imaginary eigenvalue) are represented.

Parameters:

eigenvalues (npt.NDArray[np.complex128]) – Retained eigenvalues \(\lambda\), shape (n_modes,).
natural_frequencies_hz (npt.NDArray[np.float64]) – Natural frequencies \(|\lambda| / 2\pi\), shape (n_modes,).
damping_ratios (npt.NDArray[np.float64]) – Damping ratios \(-\operatorname{Re}\lambda / |\lambda|\).
damped_frequencies_hz (npt.NDArray[np.float64]) – Damped frequencies \(\operatorname{Im}\lambda / 2\pi\).
mode_shapes (npt.NDArray[np.complex128]) – Reduced complex mode shapes (second-order displacements then first-order states), shape (ndof2 + ndof1, n_modes), phase-normalized so each mode’s dominant component is real and positive.
full_eigenvectors (npt.NDArray[np.complex128]) – Full eigenvectors over all states, shape (n_states, n_modes), sharing the same phase normalization.
full_left_eigenvectors (npt.NDArray[np.complex128]) – Full left eigenvectors over all states, shape (n_states, n_modes). Together with full_eigenvectors these support scale-invariant biorthogonal participation and first-order eigenvalue sensitivity.
n_rigid_body_modes (int) – Number of degrees of freedom without an under-damped representative (rigid-body or over-damped modes, including split rigid-body pairs).
dof_descriptions (list[str]) – Descriptions of the degrees of freedom that index the rows of mode_shapes (the second-order displacements then first-order states). Empty when descriptions were not supplied to the solver.
state_descriptions (list[str]) – Descriptions of every state indexing the full left and right eigenvectors. Empty when descriptions were not supplied to the solver.
dof_mbc_coordinates (list[str]) – Multi-blade coordinate ("collective"/"cosine"/"sine"/"") of each mode_shapes row, aligned with dof_descriptions. Empty when not supplied.
condition_numbers (npt.NDArray[np.float64]) – Per-mode eigenvalue condition number \(\kappa = 1 / |y^H x|\) (the reciprocal cosine of the angle between the left and right eigenvectors), shape (n_modes,). 1 is perfectly conditioned; large values flag eigenvalues that are numerically sensitive (highly non-normal system).
is_degenerate (npt.NDArray[np.bool]) – Per-mode flag marking modes whose eigenvalue is (near-)repeated by another retained mode, so the individual mode shape is defined only up to a rotation within the shared invariant subspace.
n_unstable (int) – Number of eigenvalues with positive real part (unstable). Non-zero is a red flag for the operating point. Split rigid-body pairs are not counted: the sign of their real part is not resolved by the data.
n_overdamped (int) – Number of non-oscillatory stable real eigenvalues (over-damped modes), which are not returned as oscillatory modes.
n_split_rigid_body_pairs (int) – Number of complex-conjugate pairs classified as numerically split rigid-body eigenvalues (see the module notes) and therefore left out of the oscillatory modes; each also counts in n_rigid_body_modes.
rotor_speed_rpm (float) – Rotor speed (rev/min) of the operating point the state matrix was linearized at, or nan when unknown (e.g. a matrix given directly to compute_modes()). modes_from_mbc() copies it from the MBC result; the labeller uses it to read a blade whirl mode’s damping in the rotating frame.

eigenvalues: npt.NDArray[np.complex128]

natural_frequencies_hz: npt.NDArray[np.float64]

damping_ratios: npt.NDArray[np.float64]

damped_frequencies_hz: npt.NDArray[np.float64]

mode_shapes: npt.NDArray[np.complex128]

full_eigenvectors: npt.NDArray[np.complex128]

n_rigid_body_modes: int

dof_descriptions: list[str]

condition_numbers: npt.NDArray[np.float64]

is_degenerate: npt.NDArray[np.bool_]

n_unstable: int = 0

n_overdamped: int = 0

dof_mbc_coordinates: list[str]

full_left_eigenvectors: npt.NDArray[np.complex128]

state_descriptions: list[str]

n_split_rigid_body_pairs: int = 0

rotor_speed_rpm: float = nan

property n_modes: int: Return the number of retained modes.

property natural_frequencies_rad_s: npt.NDArray[np.float64]: Return natural frequencies in rad/s.

property max_condition_number: float: Return the worst (largest) eigenvalue condition number, or 1 if none.

compute_modes(a, ndof2, ndof1, *, sort_by_frequency=True, descriptions=None, mbc_coordinates=None, rigid_body_frequency_hz=0.003, split_pair_rtol=0.0001)[source]

Compute modal properties from a state matrix.

Parameters:

a (npt.NDArray[np.float64]) – Square state matrix in [q2, q2dot, q1] order, shape (2 * ndof2 + ndof1, 2 * ndof2 + ndof1).
ndof2 (int) – Number of second-order degrees of freedom (the q2 block size).
ndof1 (int) – Number of first-order states (the q1 block size).
sort_by_frequency (bool, optional) – Sort the returned modes by ascending natural frequency (the default).
descriptions (list[str] or None, optional) – Descriptions of all 2 * ndof2 + ndof1 states, in the matrix order. When given, the subset that indexes the mode-shape rows is stored on the result as dof_descriptions. A list of only the ndof2 + ndof1 mode-shape rows (displacements then first-order states) is also accepted and stored as is; state_descriptions is then left empty.
mbc_coordinates (list[str] or None, optional) – Multi-blade coordinate of all states (or of the mode-shape rows), in the matrix order; the mode-shape subset is stored on the result as dof_mbc_coordinates.
rigid_body_frequency_hz (float, optional) – Natural frequency below which a complex pair whose imaginary part is not resolved by the data is classified as a split rigid-body pair (see the module notes). Default RIGID_BODY_FREQUENCY_HZ; 0.0 keeps every complex pair as an oscillatory mode.
split_pair_rtol (float, optional) – Assumed relative accuracy of a in the split-pair test. Default SPLIT_PAIR_RTOL; 0.0 keeps every complex pair.

Returns:

ModalSolution – The modal frequencies, damping ratios, and mode shapes.

Raises:

ValueError – If a is not square, if ndof2/ndof1 are not non-negative integers, if its size does not match 2 * ndof2 + ndof1, if descriptions or mbc_coordinates has neither one entry per state nor one per mode-shape row, or if rigid_body_frequency_hz or split_pair_rtol is negative or non-finite.

Return type:

ModalSolution

modes_from_mbc(result, *, rigid_body_frequency_hz=0.003, split_pair_rtol=0.0001)[source]

Compute modal properties from an MBC transform result.

Parameters:

result (MBCResult) – Output of vane.io.mbc_transform.mbc3_transform(); its avg_a must be present.
rigid_body_frequency_hz (float, optional) – Frequency floor of the split rigid-body pair test; see compute_modes().
split_pair_rtol (float, optional) – Relative accuracy of the split rigid-body pair test; see compute_modes().

Returns:

ModalSolution – The modal solution for the averaged state matrix.

Raises:

ValueError – If result.avg_a is None.

Return type:

ModalSolution

The Modal Assurance Criterion (MAC) measures the correlation between two mode shapes; a value of 1 indicates perfect correlation and 0 indicates orthogonality [1]. For complex (state-space) modes the pole-weighted MACXP criterion [2] is also provided. match_modes performs a one-to-one Hungarian assignment over a MAC (optionally frequency-penalized) matrix between two operating points; this is a pairwise building block. Cross-operating-point tracking over a whole sweep is done separately by vane.modal.identify_modes(), which extracts globally optimal continuity paths rather than chaining pairwise matches.

References

compute_mac(phi_ref, phi_test)[source]

Compute the Modal Assurance Criterion (MAC) matrix.

Parameters:

phi_ref (npt.NDArray[np.complex128]) – Reference mode-shape matrix, shape (n_dof, n_modes_ref).
phi_test (npt.NDArray[np.complex128]) – Test mode-shape matrix, shape (n_dof, n_modes_test).

Returns:

npt.NDArray[np.float64] – MAC matrix of shape (n_modes_ref, n_modes_test) with values in [0, 1].

Raises:

ValueError – If the two mode-shape matrices have incompatible first dimensions.

Return type:

npt.NDArray[np.float64]

Notes

The MAC between modes \(i\) and \(j\) is

\[\text{MAC}_{ij} = \frac{|\phi_i^H \phi_j|^2} {(\phi_i^H \phi_i)(\phi_j^H \phi_j)}.\]

compute_macxp(phi_ref, lambda_ref, phi_test, lambda_test)[source]

Compute the pole-weighted MACXP matrix for complex modes.

MACXP augments the MAC with the transpose product and weights both by the modal poles, making it more discriminating than MAC for complex state-space modes.

Parameters:

phi_ref (npt.NDArray[np.complex128]) – Reference and test mode-shape matrices, shape (n_dof, n_modes).
phi_test (npt.NDArray[np.complex128]) – Reference and test mode-shape matrices, shape (n_dof, n_modes).
lambda_ref (npt.NDArray[np.complex128]) – Corresponding modal poles (eigenvalues), shape (n_modes,).
lambda_test (npt.NDArray[np.complex128]) – Corresponding modal poles (eigenvalues), shape (n_modes,).

Returns:

npt.NDArray[np.float64] – MACXP matrix of shape (n_modes_ref, n_modes_test); a mode correlated with itself yields 1.

Raises:

ValueError – If shapes are inconsistent between mode matrices and pole vectors.

Return type:

npt.NDArray[np.float64]

Notes

The criterion is defined for damped modes (poles with a non-zero real part); an undamped pole makes its self-correlation term infinite, so the whole row (reference pole) or column (test pole) of every undamped pole is returned as NaN rather than raising – including the cross entries against damped modes, which would otherwise collapse to a misleading 0.0.

match_modes(mac, ref_frequencies=None, test_frequencies=None, frequency_weight=0.0, *, forbidden=None)[source]

Match reference modes to test modes by maximum-weight assignment.

A Hungarian (optimal) assignment maximizes the total correlation between the two mode sets. When frequencies are supplied, the MAC of each pair is scaled by 1 - frequency_weight * |df| / span so that frequency proximity breaks ties between similar shapes (the strategy used for Campbell-diagram tracking).

Parameters:

mac (npt.NDArray[np.float64]) – Correlation matrix, shape (n_ref, n_test) (e.g. from compute_mac()).
ref_frequencies (npt.NDArray[np.float64] or None, optional) – Per-mode natural frequencies for the reference and test sets. Both must be given to apply the frequency penalty.
test_frequencies (npt.NDArray[np.float64] or None, optional) – Per-mode natural frequencies for the reference and test sets. Both must be given to apply the frequency penalty.
frequency_weight (float, optional) – Strength of the frequency penalty in [0, 1]; 0 (default) uses MAC alone.
forbidden (npt.NDArray[np.bool] or None, optional) – Pairs that must not be matched, shape (n_ref, n_test). This is a hard constraint: whenever an assignment avoiding every forbidden pair exists, it is chosen.

Returns:

list[tuple[int, int]] – (ref_index, test_index) pairs, one per matched mode (min(n_ref, n_test) pairs), ordered by reference index.

Raises:

ValueError – If forbidden does not match the shape of mac, or no assignment avoids every forbidden pair.

Return type:

list[tuple[int, int]]

OpenFAST exposes no full-system mass matrix, so a classical mass-normalized modal participation factor is unavailable. Instead, participation is quantified from the right eigenvector: the magnitude of each state’s component in a mode measures how strongly that degree of freedom participates. Each mode is normalized so its dominant component has magnitude one, and a sign is assigned from the phase of each component relative to the dominant one (components more than 90 degrees out of phase are negated), giving the signed contribution used for physical mode identification.

class ParticipationResult(magnitude, signed_magnitude, phase_deg, dominant_state)[source]

Bases: object

Per-state participation in each mode.

Parameters:

magnitude (npt.NDArray[np.float64]) – Normalized participation magnitude, shape (n_dof, n_modes); each column’s maximum is 1.
signed_magnitude (npt.NDArray[np.float64]) – magnitude with the sign of components more than 90 degrees out of phase with the dominant component flipped negative.
phase_deg (npt.NDArray[np.float64]) – Phase of each component in degrees, shape (n_dof, n_modes).
dominant_state (npt.NDArray[np.int]) – Index of the largest-magnitude state in each mode, shape (n_modes,).

magnitude: npt.NDArray[np.float64]

signed_magnitude: npt.NDArray[np.float64]

phase_deg: npt.NDArray[np.float64]

dominant_state: npt.NDArray[np.int_]

compute_participation(mode_shapes, scale_factors=None)[source]

Compute per-state participation from complex mode shapes.

Parameters:

mode_shapes (npt.NDArray[np.complex128]) – Complex mode-shape matrix, shape (n_dof, n_modes).
scale_factors (npt.NDArray[np.float64] or None, optional) – Per-DOF multipliers applied before normalization (e.g. 1/blade_length for translational blade DOFs) so heterogeneous DOFs are comparable. When None, no scaling is applied.

Returns:

ParticipationResult – Normalized magnitudes, signed magnitudes, phases, and dominant states.

Raises:

ValueError – If scale_factors length does not match the number of DOFs.

Return type:

ParticipationResult

participation_from_modes(solution, scale_factors=None)[source]

Compute participation from a ModalSolution’s mode shapes.

Parameters:

solution (ModalSolution) – Modal solution whose mode_shapes are analysed.
scale_factors (npt.NDArray[np.float64] or None, optional) – Per-DOF multipliers, as in compute_participation().

Returns:

ParticipationResult – The participation result for the solution’s mode shapes.

Return type:

ParticipationResult

participation_scale_factors(descriptions, *, blade_length, tower_length)[source]

Derive per-DOF participation scale factors from the state descriptions.

A turbine’s states are a mix of units: blade and tower deflections are in metres while the other degrees of freedom are rotations (radians) or generalized coordinates. Comparing their raw eigenvector components over-weights whichever has the larger numeric units. Scaling each translational deflection by its characteristic length — blade flap/edge by the flexible blade length, tower fore-aft/side-side by the flexible tower length — turns it into a dimensionless tip-deflection ratio comparable to the rest. A BeamDyn blade’s nodal translations (along the blade-frame X, Y and Z axes, in metres) are scaled by the blade length too, so they become spanwise deflection ratios comparable with the nodal rotations, which are in radians. It builds the scale_factors array that compute_participation() accepts (replacing a hand-made one), by classifying each state with classify_dof().

Every other category — the platform rigid-body DOFs (surge/sway/heave and roll/pitch/yaw), blade pitch, drivetrain torsion, generator azimuth, furl/teeter, BeamDyn nodal rotations, and any unrecognized state — is left at 1.0 (no length scaling). Velocity states scale by the same factor as their position DOF, since they share its classification.

Only the raw-magnitude participation (compute_participation()) depends on these factors. The physical labels of vane.modal.label_solution() use the biorthogonal participation, which is invariant to any rescaling of the states and needs none.

Parameters:

descriptions (Sequence[str]) – The state descriptions, one per mode-shape row and in the same order (e.g. from the linearization file / MBC result), as classified by classify_dof().
blade_length (float) – Flexible blade length in metres (e.g. TurbineGeometry.blade_length from read_elastodyn_geometry(), TipRad - HubRad, which the ElastoDyn file defines for BeamDyn blades too). Must be finite and positive.
tower_length (float) – Flexible tower length in metres (e.g. TurbineGeometry.tower_length). Must be finite and positive.

Returns:

npt.NDArray[np.float64] – The per-DOF scale factors, shape (len(descriptions),): 1/blade_length for ElastoDyn blade flap/edge deflections and BeamDyn nodal translations, 1/tower_length for tower deflections, 1.0 otherwise. Pass it straight to compute_participation() / participation_from_modes().

Raises:

ValueError – If blade_length or tower_length is not finite and positive.

Return type:

npt.NDArray[np.float64]

Raw right-eigenvector amplitudes depend on the units chosen for the states. A metre, a radian, and an internal aerodynamic or hydrodynamic state therefore cannot be compared by magnitude alone. For a simple eigenvalue, the element-wise left–right product

\[p_{ki}=\frac{\overline{w}_{ki}v_{ki}} {\mathbf{w}_i^H\mathbf{v}_i}\]

is invariant to any nonsingular diagonal rescaling of the states. Its complex components sum to one. This module reports those factors and a non-negative share formed by normalising their magnitudes, both per state and aggregated into physical subsystems.

Individual factors are not physically unique for a repeated eigenvalue because the eigenvectors may rotate within its invariant subspace. The caller should therefore use is_degenerate as an acceptance check before interpreting an individual degenerate mode.

class BiorthogonalParticipation(complex_factors, magnitude_fractions, closure_error, valid, subsystem_names, subsystem_fractions, state_subsystems)[source]

Bases: object

Left–right participation factors for every retained oscillatory mode.

Parameters:

complex_factors (npt.NDArray[np.complex128]) – Complex state factors, shape (n_states, n_modes). Each valid column sums to one.
magnitude_fractions (npt.NDArray[np.float64]) – Absolute factors normalised to sum to one per valid mode.
closure_error (npt.NDArray[np.float64]) – Absolute difference between each complex column sum and one.
valid (npt.NDArray[np.bool]) – Whether the left–right inner product is numerically resolvable. Invalid columns contain NaN and must not be interpreted.
subsystem_names (tuple[str, ...]) – Ordered subsystem labels indexing subsystem_fractions.
subsystem_fractions (npt.NDArray[np.float64]) – Magnitude fractions summed by subsystem, shape (n_subsystems, n_modes).
state_subsystems (tuple[str, ...]) – Subsystem assigned to each state.

complex_factors: npt.NDArray[np.complex128]

magnitude_fractions: npt.NDArray[np.float64]

closure_error: npt.NDArray[np.float64]

valid: npt.NDArray[np.bool_]

subsystem_names: tuple[str, ...]

subsystem_fractions: npt.NDArray[np.float64]

state_subsystems: tuple[str, ...]

biorthogonal_participation(solution, *, subsystem_labels=None)[source]

Compute scale-invariant participation from a modal solution.

Parameters:

solution (ModalSolution) – Modal solution retaining matching full left and right eigenvectors.
subsystem_labels (sequence of str or None, optional) – Explicit subsystem label for every state. When omitted, labels are inferred from solution.state_descriptions.

Returns:

BiorthogonalParticipation – State and subsystem participation factors.

Raises:

ValueError – If left eigenvectors are unavailable, shapes disagree, or supplied labels do not match the state count.

Return type:

classify_state_subsystem(description)[source]

Classify an OpenFAST state description into an engineering subsystem.

Parameters:: description (str)
Return type:: str

Modes computed independently at successive operating points (rotor speeds or wind speeds) are linked into tracks — the lines of a Campbell diagram. Both tracking strategies score a candidate link by the same affinity (the modal-assurance criterion tempered by a frequency-continuity penalty) and forbid links below the MAC threshold; they differ only in how that affinity is resolved into tracks:

"single_path" (the default) extracts each mode line as the globally optimal continuity path through the whole sweep: it repeatedly finds the single best-continuity path over the not-yet-assigned modes (a deterministic dynamic program over the affinity) and removes it, until every mode is assigned. It reads the strongest line off first.

"simultaneous" instead resolves each operating-point transition at once: all modes on one side are matched to all modes on the next by a single maximum-weight assignment (the Hungarian algorithm, with both sides free to stay unmatched). No early high-affinity link can then claim a mode that a different pairing would use to reach a higher overall total — the failure mode of a per-line extraction in dense spectra or at near-degenerate crossings, where an earlier high-scoring path can strand a node a later path would have preferred.

Both are deterministic — no random restarts or preset cluster counts — and each track carries a confidence (its weakest link’s correlation) and an ambiguity flag (raised where a mode had two near-equally correlated continuations, i.e. a crossing or veering hotspot). Every track is given a physical label.

DEFAULT_RIGID_BODY_FREQUENCY_HZ = 0.001

Natural frequency (Hz) below which a mode is rigid-body and is not tracked.

A period of 1000 s is far longer than any restrained mode of a turbine: the softest moored floating-platform surge and sway modes sit near 0.005-0.01 Hz. Below it lie only modes without restoring stiffness, such as the free rotor azimuth.

LABEL_MISMATCH_PENALTY = 0.5

Factor applied to the affinity of a link between two differently labelled modes.

When both ends of a candidate link carry an unambiguous physical label (see vane.modal.labeler.ModeLabel.is_ambiguous) and the labels differ – another family, mode number or multi-blade type – the link’s affinity is multiplied by this factor. A confident label change between neighbouring operating points is strong evidence that the link joins two different physical modes; ambiguous (hybrid) modes, as at a veering, are not penalised.

NEAR_COINCIDENT_RTOL = 0.01

Relative eigenvalue distance within which modes of one point are near-coincident.

Two modes whose eigenvalues satisfy \(|\lambda_i - \lambda_j| \le \mathrm{rtol} \max(|\lambda_i|, |\lambda_j|)\) are mixed by any coupling of comparable size, so their individual eigenvectors are an arbitrary basis of the pair’s subspace (e.g. the collective and regressive second flap of the IEA 22-MW turbine, 0.07 % apart at 10 m/s). Their MAC with a neighbouring point’s mode then measures the mixing, not the identity. For a link between two modes carrying the same unambiguous label, the subspace MAC of each end against the other end’s near-coincident cluster is used when it is higher; the labels (assigned one per multi-blade type by vane.modal.label_solution()) then decide which cluster member continues which line.

class IdentificationResult(tracks, n_operating_points, branch_groups=<factory>, heavily_damped_tracks=<factory>, heavily_damped_modes=<factory>)[source]

Bases: object

Result of cross-operating-point mode identification.

Parameters:

tracks (list[ModeTrack]) – The identified mode tracks, ordered by their first natural frequency.
n_operating_points (int) – Number of operating points processed.
branch_groups (list[BranchGroup]) – Crossing/veering hotspots flagged by the branch-review pass (empty unless branch_review was requested). See vane.modal.branch.
heavily_damped_tracks (list[ModeTrack]) – Tracks of the heavily damped (near-critical) modes, linked among themselves only, ordered by first natural frequency. Empty when the heavily damped tier is disabled or no mode qualifies.
heavily_damped_modes (list[list[int]]) – For each operating point, the indices of the modes classified heavily damped, so they are reported even where they form no track. Empty when the tier is disabled.

tracks: list[ModeTrack]

n_operating_points: int

branch_groups: list[BranchGroup]

heavily_damped_tracks: list[ModeTrack]

heavily_damped_modes: list[list[int]]

property n_heavily_damped: int: Return the number of heavily damped modes over all operating points.

class ModeTrack(operating_points, mode_indices, natural_frequencies_hz, damping_ratios, label, confidence=1.0, is_ambiguous=False, is_heavily_damped=False, label_agreement=1.0, point_labels=<factory>)[source]

Bases: object

A mode followed across operating points.

Parameters:

operating_points (list[int]) – Indices of the operating points this track spans, in order.
mode_indices (list[int]) – The mode index within each corresponding operating point.
natural_frequencies_hz (list[float]) – Natural frequency at each operating point along the track.
damping_ratios (list[float]) – Damping ratio at each operating point along the track.
label (ModeLabel) – Representative physical label: the label carrying the largest summed confidence over the track’s operating points (its most confident instance), counting only unambiguous point labels when there are any.
confidence (float) – The weakest link correlation along the track (minimum MAC between consecutive points, or the subspace MAC across a near-coincident pair), in [0, 1]; 1.0 for a single-point track.
is_ambiguous (bool) – Whether the track’s identity is in doubt: a link was a near-tie (a mode with two near-equally correlated continuations, i.e. a crossing or veering hotspot), an unambiguous point label disagrees with the track label, every point label is ambiguous, or the track is a single operating point of a multi-point sweep (no continuity confirms it).
is_heavily_damped (bool) – Whether the track links heavily damped (near-critical) modes, which are tracked in their own tier (see identify_modes()).
label_agreement (float) – Fraction of the track’s labelled operating points whose own label equals the track label, in [0, 1].
point_labels (list[ModeLabel]) – The label of the track’s mode at each of its operating points, aligned with operating_points; empty when any of those solutions carries no DOF descriptions (the agreement and ambiguity still use the labelled ones).

operating_points: list[int]

mode_indices: list[int]

natural_frequencies_hz: list[float]

damping_ratios: list[float]

label: ModeLabel

confidence: float = 1.0

is_ambiguous: bool = False

is_heavily_damped: bool = False

label_agreement: float = 1.0

point_labels: list[ModeLabel]

heavily_damped_modes(solution, *, threshold=0.99, rotor_speed_rpm=None)[source]

Return which modes of one operating point are heavily damped.

A mode is heavily damped (near-critical) when its damping ratio, measured in the frame in which the mode is defined (rotor_frame_damping_ratios()), is at least threshold. Such a mode barely oscillates: its damped frequency is a small fraction of its natural frequency, which mostly measures the decay rate, and its shape correlates weakly with its neighbours across operating points. These are oscillatory (complex) modes; the eigensolver’s n_overdamped instead counts the real, non-oscillatory eigenvalues, which are never returned as modes.

Parameters:

solution (ModalSolution) – The modal solution of one operating point.
threshold (float, optional) – Damping ratio in (0, 1] at or above which a mode is heavily damped. Default DEFAULT_HEAVILY_DAMPED_THRESHOLD.
rotor_speed_rpm (float or None, optional) – The rotor speed (rev/min) at the operating point. None (the default) uses solution.rotor_speed_rpm, as vane.modal.label_solution() does. When neither is known, regressive and progressive blade whirl modes are never classified, since their fixed-frame damping ratio is shifted by the whirl.

Returns:

npt.NDArray[np.bool_] – Shape (n_modes,); True for each heavily damped mode.

Raises:

ValueError – If threshold is not in (0, 1] or rotor_speed_rpm is not finite.

Return type:

npt.NDArray[np.bool_]

identify_modes(solutions, *, frequency_weight=0.5, mac_threshold=0.5, ambiguity_margin=0.2, strategy='single_path', branch_review=False, resolve=False, parameter_values=None, rigid_body_frequency_hz=0.001, heavily_damped_threshold=0.99, rotor_speeds_rpm=None, continuity_metric='natural_frequency')[source]

Link modes across operating points into labeled tracks, globally.

Parameters:

solutions (Sequence[ModalSolution]) – Modal solutions, one per operating point, in operating-point order. All must share the same number of mode-shape degrees of freedom.
frequency_weight (float, optional) – Weight of the frequency-continuity penalty in the link affinity, [0, 1].
mac_threshold (float, optional) – Minimum modal assurance criterion for two modes to be linkable.
ambiguity_margin (float, optional) – A link is flagged ambiguous when the best continuation’s MAC exceeds the second best by less than this margin.
strategy ({"single_path", "simultaneous"}, optional) – How links are resolved into tracks. "single_path" (the default) extracts the globally optimal continuity path one line at a time; "simultaneous" resolves each operating-point transition with one maximum-weight assignment, which is more reliable where lines cross or veer in a dense spectrum. The two agree on well-separated spectra and differ only at contested transitions; see the module docstring.
branch_review (bool, optional) – When True, run the branch-review pass and attach the detected crossing/veering hotspots to the result’s branch_groups (the tracks themselves are unchanged). Default False. See vane.modal.branch.
resolve (bool, optional) – When True, also attach the smooth (minimum-curvature) alternative to each eligible branch group (implies branch_review; the tracks are still not modified). Default False.
parameter_values (Sequence[float] or None, optional) – The operating-parameter value at each operating point, used only by resolve as the curvature abscissa so smoothness is measured against the real (possibly non-uniform) sweep spacing. Defaults to the operating-point index (uniform spacing).
rigid_body_frequency_hz (float, optional) – Modes whose undamped natural frequency is below this value (Hz) are rigid-body modes with no restoring stiffness and are left out of every track. Default DEFAULT_RIGID_BODY_FREQUENCY_HZ; 0.0 tracks every mode.
heavily_damped_threshold (float or None, optional) – Damping ratio, in (0, 1], at or above which a mode is heavily damped (see heavily_damped_modes()). Heavily damped modes are kept out of the main tracks and linked among themselves only, into heavily_damped_tracks, so they can neither take over nor split a lightly damped line; every one is listed per operating point in heavily_damped_modes. Default DEFAULT_HEAVILY_DAMPED_THRESHOLD. None disables the tier and tracks every mode together.
rotor_speeds_rpm (Sequence[float] or None, optional) – Rotor speed (rev/min) at each operating point. Needed to measure the damping of a regressive or progressive blade whirl mode in the rotating frame (see rotor_frame_damping_ratios()). None (the default) uses each solution’s own rotor_speed_rpm (set by vane.modal.eigensolver.modes_from_mbc()), as vane.modal.label_solution() does; at a point whose rotor speed is unknown (nan) such modes are never classified heavily damped, because their fixed-frame damping ratio is shifted by the whirl and is not a property of the mode.
continuity_metric ({"natural_frequency", "eigenvalue"}, optional) – The distance the continuity penalty measures between two modes of the main tracks. "natural_frequency" (the default) is the difference of undamped natural frequencies; "eigenvalue" is the distance \(|\lambda_i - \lambda_j| / 2\pi\) in the complex plane, which equals it for lightly damped modes and also weighs a change of decay rate. The heavily damped tier always uses "eigenvalue", since a near-critical mode’s natural frequency mostly measures its decay rate.

Returns:

IdentificationResult – The identified tracks and the number of operating points.

Raises:

ValueError – If frequency_weight, mac_threshold, or ambiguity_margin is not in [0, 1], rigid_body_frequency_hz is negative or non-finite, heavily_damped_threshold is not in (0, 1], rotor_speeds_rpm has the wrong length or non-finite values, strategy or continuity_metric is unknown, or the solutions have inconsistent mode-shape DOF layout.

Return type:

IdentificationResult

Notes

The free rotor-azimuth (generator) DOF has no stiffness: its azimuth and speed states give a zero and an aerodynamic-damping eigenvalue, which the eigensolver normally returns as real and drops. Where the two nearly coincide they can come back as a complex pair of negligible frequency (periods of tens of minutes), so the mode would appear at isolated operating points only. The rigid_body_frequency_hz floor removes it everywhere.

A blade mode whose aerodynamic damping exceeds critical in the rotating frame has two real rotating-frame eigenvalues \(-\sigma_1, -\sigma_2\). The MBC transform maps each cyclic pair of them to a fixed-frame pair \(-\sigma_k \pm i\Omega\): an oscillation at the rotor frequency whose natural frequency \(\sqrt{\sigma_k^2 + \Omega^2}\) measures the decay rate rather than any vibration, while the collective pair is real and is dropped by the eigensolver. Tracking those images by natural frequency against the lightly damped whirl lines either side of the transition draws spurious lines; the heavily damped tier keeps them apart.

rotor_frame_damping_ratios(solution, rotor_speed_rpm, multiblade)[source]

Return each mode’s damping ratio in the frame in which the mode is defined.

Parameters:

solution (ModalSolution) – The modal solution of one operating point (in multi-blade coordinates).
rotor_speed_rpm (float) – The rotor speed (rev/min) at that operating point.
multiblade (Sequence[str or None]) – The multi-blade type of each mode ("collective", "regressive", "progressive", "cyclic" or None), e.g. the multiblade of vane.modal.label_solution().

Returns:

npt.NDArray[np.float64] – Shape (n_modes,). For a regressive or progressive whirl mode, the damping ratio of the rotating-frame eigenvalue it is the image of; for every other mode (collective, tower, platform, drivetrain, unlabelled), the fixed-frame damping ratio. A "cyclic" mode of undetermined whirl takes the smaller of the two whirl readings.

Raises:

ValueError – If multiblade does not have one entry per mode or rotor_speed_rpm is not finite.

Return type:

npt.NDArray[np.float64]

Notes

The MBC transform shifts a cyclic blade mode’s rotating-frame eigenvalue \(\lambda_r = -\sigma + i\omega_r\) by the rotor frequency \(\Omega\): the progressive whirl appears at \(\omega_r + \Omega\) and the regressive at \(|\omega_r - \Omega|\), with the same decay rate \(\sigma\). The fixed-frame damping ratio \(\sigma / |\lambda|\) therefore differs between the two whirls of one blade mode and rises towards 1 on the regressive branch as \(\omega_r\) approaches \(\Omega\), without the blade mode itself being any more damped. Undoing the shift, \(\omega_r = |\omega \mp \Omega|\), gives the damping ratio \(\sigma / \sqrt{\sigma^2 + \omega_r^2}\) of the blade mode, which is the same for its regressive, collective and progressive members.

Each mode is labeled by the physical degree-of-freedom category that dominates it. Participation is aggregated per DofCategory (via vane.config.dof_map.classify_dof()), the dominant category names the mode (e.g. “1st Tower Fore-Aft”), and the fraction of participation it carries is reported as a confidence — a low value flags an ambiguous, mixed mode.

label_solution() votes with the scale-invariant left–right (biorthogonal) participation of vane.modal.biorthogonal, so the many unclassified module states of a coupled model (mooring line nodes, hydrodynamic radiation states, aerodynamic states) cannot out-vote the structural degrees of freedom merely by having large raw eigenvector amplitudes in their own units.

BeamDyn blades have no modal DOFs: their nodal states vote as flapwise, edgewise, torsional, or axial blade motion (see vane.config.dof_map), and label_solution() numbers the resulting flap, edge, and torsion modes from the spanwise shape of their section rotation and their frequency order.

Ambiguity is reported, never resolved silently. A mode whose runner-up category carries at least LABEL_AMBIGUITY_RATIO of the winner’s weight (a hybrid, e.g. a monopile’s second tower fore-aft mode mixed with the progressive second flap), or whose multi-blade type is not decided by its collective/cyclic split and whirl, is returned with is_ambiguous=True and the runner-up as alternative. Within one operating point each blade mode family (e.g. the second flap) has exactly one collective, one regressive and one progressive member; label_solution() enforces this (see label_solution(), Notes).

BEAMDYN_RIGID_RANGE = 0.1

Spanwise rotation spread below which a BeamDyn blade mode counts as rigid.

The linearized BeamDyn nodal states carry the rigid motion of the blade root. When the section rotation varies along the span by less than this fraction of its largest value, the blade turns as a rigid body and the mode is not an elastic bending mode; a rigid collective edgewise rotation (all blades turning together in the rotor plane) is the rotor-azimuth mode.

BEAMDYN_SHAPE_TOLERANCE = 0.05

Relative size below which a spanwise rotation increment is ignored.

The order of a BeamDyn bending or torsion mode is one plus the number of sign changes of the increments of its nodal section rotation along the span; increments smaller than this fraction of the largest one are treated as numerical noise and skipped.

DEFAULT_HEAVILY_DAMPED_THRESHOLD = 0.99

Damping ratio at or above which a mode is heavily damped (near-critical).

The ratio is measured in the frame in which the mode is defined: the rotating frame for a regressive or progressive blade whirl mode (see vane.modal.identifier.rotor_frame_damping_ratios()), the fixed frame otherwise. 0.99 means within 1 % of critical damping, where the damped frequency is below 15 % of the natural frequency and the natural frequency \(|\lambda|\) is essentially a decay rate. It is set from the reference-turbine sweeps (NREL 5-MW land and OC3 monopile, IEA 3.4-MW, IEA 10-MW and IEA 15-MW monopile, CalcSteady with quasi-steady aero): every first-flap Campbell line that tracks cleanly stays at or below 0.95 in this frame (its fixed-frame value reaches 0.998 on the regressive branch), while the modes that broke the IEA 15-MW lines above rated sit at 1.000, i.e. past critical damping in the rotating frame. Lightly damped lines that the community still draws (first flap at 0.25-0.78 in published IEA Campbell diagrams) are far below it.

DEFAULT_MIN_KNOWN_PARTICIPATION = 0.5

Default minimum share of participation that classified DOFs must carry.

A mode is named after a physical DOF category only when the classified (structural) degrees of freedom carry at least half of its total participation, i.e. when the structure – not unclassified module states – is the majority participant. Below this the mode is reported as "Unidentified".

DRIVETRAIN_ROOT_SHARE = 0.25

Minimum in-phase root rotation of a BeamDyn drivetrain-torsion mode.

With the drivetrain flexible (DrTrDOF) and the generator locked (no GenDOF), the lowest collective edgewise BeamDyn mode is the drivetrain torsion: the whole rotor swings against the shaft spring, so the blade roots rotate in phase with the tips by a large fraction of the tip rotation (one half on the NREL 5-MW). In a collective edgewise bending mode the hub instead stays put or counter-rotates. A collective edgewise mode whose root section rotation is in phase with its peak rotation and at least this fraction of it is named "Drivetrain Torsion".

LABEL_AMBIGUITY_RATIO = 0.75

Runner-up to winner weight ratio at or above which a label is ambiguous.

The category vote (and, for a blade mode, the collective-versus-cyclic split) names a mode after its largest share. When the runner-up carries at least this fraction of the winner’s weight – e.g. 0.40 against 0.53 – the mode is a hybrid of the two, and which name it gets is decided by a few percent of participation that move with the operating point. The label is then reported as ambiguous with the runner-up as its alternative. 0.75 is set from the reference-turbine sweeps: the clean modes of the NREL 5-MW, IEA 3.4-, 10-, 15- and 22-MW turbines have runner-up ratios below 0.4, while the hybrids that flip labels between neighbouring operating points (monopile tower/flap, flap/edge veering, flap/rotor-speed, aero-state/flap) sit between 0.8 and 1.0.

TOWER_SUPPORT_SHARE = 0.3333333333333333

Minimum share of a support plane’s participation that tower bending must carry.

A support plane groups the platform translation and tilt with the tower bending DOFs of one plane (fore-aft: surge, pitch and the tower fore-aft modes; side-side: sway, roll and the tower side-side modes). On a fixed-bottom support whose substructure flexibility is carried by the platform DOFs (e.g. a monopile), the global tower bending modes put a large share of their participation on platform translation, so a per-category vote would call them platform modes. When tower bending carries at least this share of the plane’s participation and the plane as a whole out-votes every other category, the mode is a tower bending mode of that plane. A rigid-body platform mode of a floating turbine has (near-)zero tower participation and is never regrouped.

WHIRL_CIRCULARITY_THRESHOLD = 0.2

Circularity below which a cyclic blade mode’s whirl direction is undetermined.

The circularity \(2\operatorname{Im}(q_s \overline{q_c}) / (|q_c|^2 + |q_s|^2)\) is +1/-1 for a pure backward/forward whirl and 0 for a standing pattern; below this magnitude the mode is a standing ("cyclic") pattern, e.g. a mixture of the regressive and progressive members of a near-coincident pair.

class ModeLabel(category, label, confidence, dominant_dofs, multiblade=None, is_ambiguous=False, alternative=None, alternative_category=None, alternative_confidence=0.0)[source]

Bases: object

Physical label for a single mode.

Parameters:

category (DofCategory) – The dominant DOF category.
label (str) – Human-readable name of the dominant category.
confidence (float) – Fraction of total participation carried by the dominant category, in [0, 1]; low values indicate a mixed or ambiguous mode. For an "Unidentified" mode it is the share carried by unclassified states.
dominant_dofs (list[str]) – Descriptions of the highest-participation degrees of freedom (up to three).
multiblade (str or None) – For a blade mode after the MBC transform, the multi-blade type "collective", "regressive", "progressive", or "cyclic" (a standing cyclic mode with no whirl direction); None for non-blade modes or when no multi-blade information is available.
is_ambiguous (bool, optional) – Whether the label is not decided by the mode’s participation: the runner-up category carries at least LABEL_AMBIGUITY_RATIO of the winner’s weight, the multi-blade type is not decided (collective and cyclic shares within that ratio, or a standing cyclic pattern), or the per-point multi-blade assignment of label_solution() overrode the mode’s own type. Default False.
alternative (str or None, optional) – The strongest competing label: the runner-up category of the vote, the competing multi-blade type of an undecided blade mode, or the label the mode had before a multi-blade reassignment; None when nothing competes. It is given for unambiguous labels too (as the runner-up); is_ambiguous says whether it is a close competitor.
alternative_category (DofCategory or None, optional) – The category of alternative.
alternative_confidence (float, optional) – The share of the participation carried by alternative (0.0 when there is none).

category: DofCategory

label: str

confidence: float

dominant_dofs: list[str]

multiblade: str | None = None

is_ambiguous: bool = False

alternative: str | None = None

alternative_category: DofCategory | None = None

alternative_confidence: float = 0.0

category_to_label(category)[source]

Return the human-readable label for a DOF category.

Parameters:: category (DofCategory) – The category to name.
Returns:: str – The display label ("Unidentified" for unknown categories).
Return type:: str

label_mode(magnitudes, descriptions, *, multiblade=None, min_known_fraction=None)[source]

Label one mode from its per-DOF participation weights.

Parameters:

magnitudes (npt.NDArray[np.float64]) – Non-negative participation weight of each DOF, shape (n_dof,): raw mode-shape magnitudes, or (preferably) the scale-invariant participation fractions used by label_solution().
descriptions (Sequence[str]) – DOF descriptions parallel to magnitudes.
multiblade (str or None, optional) – Multi-blade type ("collective"/"regressive"/"progressive") for a blade mode; appended to the label and stored on the result.
min_known_fraction (float or None, optional) – When None (the default), the plain plurality vote: the category with the largest summed weight wins, DofCategory.UNKNOWN included. When a number in [0, 1] is given, the dominant category is the largest classified (non-UNKNOWN) category, accepted only if the classified categories together carry at least this fraction of the total weight; otherwise the mode is "Unidentified". On this (participation) path a support plane – the platform translation and tilt plus the tower bending DOFs of one plane – votes as one group when tower bending carries at least TOWER_SUPPORT_SHARE of it; if the group out-votes every other category the mode is named after its dominant tower DOF.

Returns:

ModeLabel – The dominant category, its label, the confidence, and the top DOFs. The confidence is the dominant category’s share of the total weight (the whole support plane’s share for a regrouped tower mode); for an "Unidentified" mode it is the share carried by unclassified states.

Raises:

ValueError – If magnitudes and descriptions have different lengths, or if min_known_fraction is outside [0, 1] or non-finite.
TypeError – If min_known_fraction is not a real number.

Return type:

ModeLabel

label_modes(participation, descriptions, *, min_known_fraction=None)[source]

Label every mode of a participation result.

Parameters:

participation (ParticipationResult) – Per-DOF participation (its magnitude columns are one mode each).
descriptions (Sequence[str]) – DOF descriptions parallel to the participation rows.
min_known_fraction (float or None, optional) – Forwarded to label_mode(); None (the default) keeps the plain plurality vote.

Returns:

list[ModeLabel] – One label per mode (column).

Return type:

list[ModeLabel]

label_solution(solution, *, min_known_participation=0.5, rotor_speed_rpm=None)[source]

Label every mode of a modal solution by its biorthogonal participation.

For mode \(k\) with right and left eigenvectors \(\mathbf{x}_k\) and \(\mathbf{y}_k\) of the full state matrix, the participation of state \(i\) is \(p_{ik} \propto |\overline{y}_{ik} x_{ik}|\), normalised so that \(\sum_i p_{ik} = 1\) (see vane.modal.biorthogonal.biorthogonal_participation()). The displacement and velocity states of a second-order DOF are summed onto that DOF, and the shares are voted per DofCategory by label_mode() with min_known_fraction=min_known_participation: the largest classified category names the mode if the classified DOFs carry at least min_known_participation of it, otherwise the mode is "Unidentified". The confidence is the dominant category’s share of the mode’s participation.

Platform translation/tilt and tower bending of one plane vote together when tower bending carries at least TOWER_SUPPORT_SHARE of that plane’s participation, so the global tower modes of a fixed-bottom support (whose substructure flexibility sits in the platform DOFs) are named tower modes, not platform modes. The tower modes of each plane are then numbered in order of frequency ("3rd Tower Fore-Aft" for the third), never below the number of their dominant tower DOF.

A non-degenerate rotor mode carries its multi-blade type (collective, regressive, progressive, or a standing cyclic pattern), decided from the collective/cyclic split of its participation and the whirl of its dominant cosine/sine pair.

A BeamDyn blade mode (one voted BLADE_FLAP, BLADE_EDGE, or BLADE_TORSION) is then numbered, e.g. "2nd Blade Flap (Collective)". Its shape order is one plus the number of sign changes of the spanwise increments of its section rotation (about Y for flap, X for edge, Z for torsion), which is blind to the rigid root rotation the nodal states carry. Within a family the modes of one multi-blade type are numbered in frequency order, each at least its shape order. A mode whose section rotation barely varies along the span (BEAMDYN_RIGID_RANGE) is rigid blade motion, not bending: a rigid collective edgewise mode is the rotor-azimuth mode ("Rotor/Generator"), and any other rigid mode keeps its unnumbered family label.

Parameters:

solution (ModalSolution) – A solution whose dof_descriptions are populated (i.e. produced with descriptions, as by vane.modal.eigensolver.modes_from_mbc()).
min_known_participation (float, optional) – Minimum share of the participation, in [0, 1], that classified DOFs must carry for a mode to receive a physical label (default DEFAULT_MIN_KNOWN_PARTICIPATION, 0.5: a majority).
rotor_speed_rpm (float or None, optional) – Rotor speed (rev/min) of the operating point, used to read a whirl mode’s damping in the rotating frame so heavily damped modes stay out of the per-point multi-blade assignment. Default None uses solution.rotor_speed_rpm (set by vane.modal.eigensolver.modes_from_mbc()).

Returns:

list[ModeLabel] – One label per mode.

Raises:

ValueError – If the solution carries no DOF descriptions, or min_known_participation is outside [0, 1] or non-finite.
TypeError – If min_known_participation is not a real number.

Return type:

list[ModeLabel]

Notes

A solution without usable left eigenvectors (e.g. constructed by hand), or an individual mode whose left–right product is numerically unresolvable, falls back to the plurality vote over raw mode-shape magnitudes. The multi-blade type is decided from the mode’s MBC coordinates – the collective/cyclic split from its participation (or, without it, from the blade energy of the mode shape) and the whirl from the shape’s cosine/sine phase; on the participation path it is attached only to a blade or "Unidentified" mode, never to a mode the vote assigns to the tower, drivetrain, or platform.

Ambiguity. A label whose runner-up category carries at least LABEL_AMBIGUITY_RATIO of the winner’s weight is returned with is_ambiguous=True and the runner-up as alternative; so is a blade mode whose collective and cyclic shares are within that ratio, or whose whirl is a standing pattern ("cyclic").

One mode per multi-blade type. Each blade mode family (e.g. the second flap) of a three-bladed rotor has one collective, one regressive and one progressive member, the regressive below the progressive. Where near-coincident members mix and break this at one point, the family’s lightly damped members are assigned to the three types jointly (best summed fit subject to the whirl frequency order); a reassigned member is marked ambiguous, and a member left over is renamed after its non-blade alternative (e.g. a tower or platform mode it is mixed with) or keeps its unsuffixed family name, ambiguous either way. Heavily damped modes (DEFAULT_HEAVILY_DAMPED_THRESHOLD, read in the rotating frame for a whirl mode) are left out of the assignment: the fixed-frame images of an overdamped blade mode whirl at the rotor speed and are not members of a whirl pair.

BeamDyn drivetrain. With a flexible drivetrain, a BeamDyn model’s drivetrain-torsion mode votes for the generator azimuth (generator free) or for collective edgewise motion (generator locked); it is renamed "Drivetrain Torsion" from its blade-root rotation (see DRIVETRAIN_ROOT_SHARE).

The tower modes of each plane are numbered after the multi-blade assignment, so a tower/blade hybrid that loses its blade type to a purer family member (and is renamed after its tower alternative) is counted among the tower modes.

Cross-operating-point tracking (vane.modal.identifier) links modes into the lines of a Campbell diagram. Where two lines cross or veer (approach, exchange character, then repel), a per-transition tracker is least certain which mode continues which line. This module detects those contested clusters and surfaces them as auditable BranchGroup records — a branch-review view — rather than quietly trusting the automatic assignment.

Detection is deterministic and conservative. A pair of tracks is flagged only where both their frequencies approach (within a scale-adaptive tolerance) and their mode shapes genuinely compete (an ambiguous link or elevated cross-correlation across a transition). Frequency proximity alone is not enough: two modes with orthogonal shapes that merely pass close in frequency are tracked unambiguously and are not a hazard, so they are not flagged.

The pass adds no risk to the tracks themselves — it only reports. Re-drawing contested clusters is a separate, opt-in step (see the resolve option of vane.modal.identify_modes()).

class BranchGroup(track_indices, op_lo, op_hi, frequency_band_hz, kind, min_separation_hz, min_separation_op, sub_windows, is_dense, resolved=False, smooth_branches=None)[source]

Bases: object

A cluster of tracks contested at a crossing or veering hotspot.

Parameters:

track_indices (tuple[int, ...]) – Indices (ascending) into IdentificationResult.tracks of the tracks in the cluster.
op_lo (int) – Hull operating-point window spanning all of the cluster’s contested windows.
op_hi (int) – Hull operating-point window spanning all of the cluster’s contested windows.
frequency_band_hz (tuple[float, float]) – Minimum and maximum natural frequency of the member tracks within the hull window.
kind (BranchKind) – Group-level classification — BranchKind.CROSSING if any member pair crosses, otherwise BranchKind.VEERING.
min_separation_hz (float) – Closest frequency approach between any member pair within the window.
min_separation_op (int) – Operating-point index at which the closest approach occurs.
sub_windows (tuple[BranchSubWindow, ...]) – The distinct contested windows that make up the group, ordered canonically.
is_dense (bool) – Whether the group has more than two tracks. Dense groups are still surfaced for review; resolution handles them up to a small branch cap.
resolved (bool) – Whether a resolution pass computed a smooth alternative for this group (always False for detection-only runs).
smooth_branches (tuple[tuple[float, ...], ...] or None) – The minimum-curvature (“smooth”, non-crossing) frequency alternative for the contested cluster, one tuple per branch aligned with the window operating points op_lo..op_hi. Set by the resolution pass for an eligible group, else None. The actual tracks are never modified — this is review-only metadata contrasting the smooth convention with the shape-following base tracks.

track_indices: tuple[int, ...]

op_lo: int

op_hi: int

frequency_band_hz: tuple[float, float]

kind: BranchKind

min_separation_hz: float

min_separation_op: int

sub_windows: tuple[BranchSubWindow, ...]

is_dense: bool

resolved: bool = False

smooth_branches: tuple[tuple[float, ...], ...] | None = None

class BranchKind(*values)[source]

Bases: Enum

Whether a contested window is a frequency crossing or a veering.

CROSSING = 'crossing'

VEERING = 'veering'

class BranchSubWindow(op_lo, op_hi, kind, truncated)[source]

Bases: object

A contiguous operating-point window where two tracks are contested.

Parameters:

op_lo (int) – First and last operating-point index of the window (op_hi > op_lo).
op_hi (int) – First and last operating-point index of the window (op_hi > op_lo).
kind (BranchKind) – Whether the two tracks cross (their frequency order swaps) or veer (approach and separate without swapping) over the window.
truncated (bool) – Whether the closest approach is at a window endpoint, so the hotspot may extend beyond the swept range.

op_lo: int

op_hi: int

kind: BranchKind

truncated: bool

attach_branch_groups(result, solutions, *, resolve=False, parameter_values=None, **kwargs)[source]

Return a copy of result with its branch_groups populated.

Detection does not alter the tracks; the returned result shares the same track objects and only carries the additional branch groups.

Parameters:

result (IdentificationResult) – The tracking result to review.
solutions (Sequence[ModalSolution]) – The per-operating-point modal solutions, in operating-point order.
resolve (bool, optional) – When True, also compute the smooth (minimum-curvature) alternative for each eligible group (see resolve_branch_groups()); the tracks are still not modified. Default False.
parameter_values (Sequence[float] or None, optional) – The operating-parameter value at each operating point, forwarded to the resolution curvature (see resolve_branch_groups()).
**kwargs – Forwarded to detect_branch_groups() (veering_tol_hz, mac_competition, ambiguity_margin).

Returns:

IdentificationResult – A new result with the detected (and optionally resolved) branch groups.

Return type:

IdentificationResult

detect_branch_groups(result, solutions, *, veering_tol_hz=None, mac_competition=0.25, ambiguity_margin=0.2)[source]

Find crossing/veering hotspots among a result’s tracks.

Parameters:

result (IdentificationResult) – The tracking result whose tracks are reviewed. Not modified.
solutions (Sequence[ModalSolution]) – The per-operating-point modal solutions the tracks were built from, in operating-point order (used for the mode-shape correlations).
veering_tol_hz (float or None, optional) – Frequency proximity below which two tracks may be contested. None (the default) derives it deterministically as 0.25 times the median adjacent natural-frequency spacing across the sweep, so it scales with the spectrum.
mac_competition (float, optional) – Cross-MAC at or above which two tracks are deemed to compete across a transition.
ambiguity_margin (float, optional) – Two non-negligible continuations whose MAC differs by less than this are a near-tie (an ambiguous link).

Returns:

list[BranchGroup] – The contested clusters, ordered canonically by window then frequency. Empty when no tracks are contested.

Raises:

ValueError – If mac_competition or ambiguity_margin is not in [0, 1], or veering_tol_hz is negative.

Return type:

list[BranchGroup]

resolve_branch_groups(groups, result, *, parameter_values=None)[source]

Annotate each eligible group with its smooth (minimum-curvature) alternative.

For a group of two to four tracks spanning at least three operating points where every track is present throughout the window, computes the assignment of the group’s modes to branches that minimizes the total squared frequency curvature — the smooth, non-crossing convention — and attaches it as smooth_branches with resolved=True. The tracks are never modified; this is review-only metadata. Larger groups, short windows, and ragged membership are left unresolved.

Parameters:

groups (list[BranchGroup]) – The detected branch groups.
result (IdentificationResult) – The tracking result the groups index (for the member-track frequencies).
parameter_values (Sequence[float] or None, optional) – The operating-parameter value at each operating point, used as the abscissa for the curvature so smoothness is measured against the real (possibly non-uniform) sweep spacing. None (the default) falls back to the operating-point index (uniform spacing). When given, it must have one value per operating point and be strictly increasing.

Returns:

list[BranchGroup] – New groups, with the smooth alternative attached where eligible.

Return type:

list[BranchGroup]

Two physically grounded uncertainty sources are combined into one per-mode confidence:

Azimuth spread. The MBC transform produces one non-rotating state matrix per azimuth; their average is the linear-time-invariant model. For an isotropic rotor every per-azimuth matrix is identical (azimuth-invariant to machine precision), so the eigenvalue spread across azimuths is ~0; for an anisotropic rotor the spread grows, quantifying how well the averaged model represents the periodic system.
Numerical conditioning and degeneracy from the eigen-analysis.

The unified confidence multiplies independent reliability factors (each in [0, 1]) so that a mode is trusted only when it is numerically well posed, non-degenerate, azimuth-stable, and (optionally) confidently tracked. It feeds the covariance initialization of the state-space export.

class AzimuthSpread(natural_frequency_std, damping_ratio_std, n_azimuths)[source]

Bases: object

Per-mode variation of the modal estimates across azimuth.

Parameters:

natural_frequency_std (npt.NDArray[np.float64]) – Standard deviation of each averaged mode’s natural frequency (Hz) across the per-azimuth perturbations of the averaged model, one entry per mode of vane.modal.eigensolver.modes_from_mbc() of the same result, in its order.
damping_ratio_std (npt.NDArray[np.float64]) – Standard deviation of each averaged mode’s damping ratio across azimuths.
n_azimuths (int) – Number of azimuth samples used.

natural_frequency_std: npt.NDArray[np.float64]

damping_ratio_std: npt.NDArray[np.float64]

n_azimuths: int

azimuth_spread(result)[source]

Compute the per-mode azimuth spread of a retained MBC result.

Rather than comparing per-azimuth spectra directly, this measures how each frozen-time matrix A(psi) perturbs the averaged model: for an isotropic rotor every A(psi) == avg_a and the spread is zero, while anisotropy makes the per-azimuth matrices (and their spectra) differ by an amount the spread captures. For each averaged mode the first-order eigenvalue perturbation dlambda = y^H (A(psi) - avg_a) x / (y^H x) (left eigenvector y, right x) is evaluated at every azimuth, and the standard deviation of the resulting natural frequency and damping is returned. It is zero for an isotropic rotor (A(psi) == avg_a) and grows with anisotropy.

Parameters:: result (MBCResult) – An MBC result computed with retain_per_azimuth=True.
Returns:: AzimuthSpread – The per-mode frequency and damping spread.
Raises:: ValueError – If the per-azimuth matrices were not retained or avg_a is absent.
Return type:: AzimuthSpread

unified_mode_confidence(solution, *, frequency_spread=None, track_confidence=None, spread_scale=0.05)[source]

Combine the uncertainty sources into one per-mode confidence in [0, 1].

The confidence is the product of independent reliability factors: numerical conditioning (1 / kappa), a degeneracy penalty, an azimuth-stability factor exp(-relative_spread / spread_scale), and an optional tracking confidence.

Parameters:

solution (ModalSolution) – The modal solution (provides condition numbers and degeneracy flags).
frequency_spread (npt.NDArray[np.float64] or None, optional) – Per-mode natural-frequency standard deviation (e.g. from azimuth_spread()); nan entries are treated as zero spread.
track_confidence (npt.NDArray[np.float64] or None, optional) – Per-mode tracking confidence in [0, 1] from the cross-operating-point tracker.
spread_scale (float, optional) – Relative-spread scale at which the azimuth-stability factor falls to 1/e.

Returns:

npt.NDArray[np.float64] – The per-mode confidence.

Return type:

npt.NDArray[np.float64]

vane.modal.unified_mode_confidence() returns a per-mode confidence in [0, 1] built from physically grounded factors (numerical conditioning, degeneracy, azimuth spread, tracking ambiguity). That confidence is only useful if it is calibrated — among the modes assigned confidence ~c, about a fraction c should be correct. A raw confidence that is systematically over- or under-confident misleads any downstream decision (which modes to trust, how to weight the Kalman covariance).

This module measures that calibration against a ground-truth correctness label and, when the raw confidence is miscalibrated, learns a monotone recalibration map so the reported number can be read as a probability of being correct:

calibrate_confidence() bins (confidence, correct) pairs into a reliability diagram and reports the expected/maximum calibration error and the Brier score, plus a pool-adjacent-violators (isotonic) map confidence -> P(correct).
recalibrate() applies that map to new confidences.
confidence_threshold() reads off the smallest confidence at which the calibrated probability of being correct reaches a target — the evidence behind a claim like “confidence >= 0.85 implies >= 95 % correct”.

The correct label is supplied by the caller and is domain-specific: for mode identification it is predicted_label == true_label against a synthetic ground truth; for cross-operating-point tracking it is whether a track was assigned to the right mode. The calibration itself is agnostic to how correctness was decided.

class ConfidenceCalibration(bin_edges, bin_confidence, bin_accuracy, bin_count, expected_calibration_error, max_calibration_error, brier_score, map_confidence, map_accuracy, n_samples)[source]

Bases: object

The calibration of a confidence score against a correctness label.

Parameters:

bin_edges (npt.NDArray[np.float64]) – The n_bins + 1 equal-width bin edges spanning [0, 1].
bin_confidence (npt.NDArray[np.float64]) – Mean confidence within each bin, shape (n_bins,); nan for an empty bin.
bin_accuracy (npt.NDArray[np.float64]) – Empirical fraction correct within each bin, shape (n_bins,); nan for an empty bin. The reliability diagram plots bin_confidence vs bin_accuracy.
bin_count (npt.NDArray[np.int]) – Number of samples in each bin, shape (n_bins,).
expected_calibration_error (float) – Sample-weighted mean absolute gap between confidence and accuracy across non-empty bins (ECE); 0 is perfectly calibrated.
max_calibration_error (float) – Largest absolute confidence-accuracy gap over non-empty bins (MCE).
brier_score (float) – Mean squared error of confidence against the correctness label; lower is better.
map_confidence (npt.NDArray[np.float64]) – Strictly increasing confidence values of the isotonic recalibration map.
map_accuracy (npt.NDArray[np.float64]) – Non-decreasing calibrated P(correct) at each map_confidence point.
n_samples (int) – Number of (confidence, correct) pairs the calibration was built from.

bin_edges: npt.NDArray[np.float64]

bin_confidence: npt.NDArray[np.float64]

bin_accuracy: npt.NDArray[np.float64]

bin_count: npt.NDArray[np.int_]

expected_calibration_error: float

max_calibration_error: float

brier_score: float

map_confidence: npt.NDArray[np.float64]

map_accuracy: npt.NDArray[np.float64]

n_samples: int

calibrate_confidence(confidence, correct, *, n_bins=10)[source]

Calibrate a confidence score against a ground-truth correctness label.

Builds an equal-width reliability diagram over [0, 1], the expected (ECE) and maximum (MCE) calibration errors, the Brier score, and an isotonic (monotone) recalibration map confidence -> P(correct) fitted by pool-adjacent-violators.

Parameters:

confidence (npt.ArrayLike) – Per-sample confidence in [0, 1] (e.g. from vane.modal.unified_mode_confidence()).
correct (npt.ArrayLike) – Per-sample correctness label, boolean or 0/1, aligned with confidence.
n_bins (int, optional) – Number of equal-width reliability bins over [0, 1]. Default 10.

Returns:

ConfidenceCalibration – The reliability diagram, calibration-error metrics, Brier score, and isotonic recalibration map.

Raises:

ValueError – If the inputs are not equal-length non-empty 1-D arrays, confidence is non-finite or outside [0, 1], correct is not boolean/0/1, or n_bins is not a positive integer.

Return type:

ConfidenceCalibration

confidence_threshold(calibration, target_accuracy)[source]

Return the smallest confidence whose calibrated P(correct) reaches a target.

Inverts the same piecewise-linear curve recalibrate() evaluates, so the returned confidence c is the lowest value with recalibrate(c) >= target_accuracy: when the target falls between two map points the crossing confidence is linearly interpolated, rather than rounded up to the next sampled point. The answer is reported on the observed confidence span; a target at or below the lowest mapped accuracy returns the lowest mapped confidence.

Parameters:

calibration (ConfidenceCalibration) – A calibration from calibrate_confidence().
target_accuracy (float) – The desired probability of being correct, in (0, 1].

Returns:

float – The smallest confidence whose calibrated probability meets the target.

Raises:

ValueError – If target_accuracy is not in (0, 1], or the calibrated probability never reaches it (the confidence is not discriminative enough for this target).

Return type:

recalibrate(calibration, confidence)[source]

Map raw confidence to a calibrated probability of being correct.

Linearly interpolates confidence onto the isotonic recalibration map; values below or above the fitted range are clamped to the map’s end values.

Parameters:

calibration (ConfidenceCalibration) – A calibration from calibrate_confidence().
confidence (npt.ArrayLike) – Raw confidence value(s) in [0, 1].

Returns:

npt.NDArray[np.float64] – The calibrated probability of being correct, same shape as confidence.

Raises:

ValueError – If confidence is non-finite or outside [0, 1].

Return type:

npt.NDArray[np.float64]

The azimuth-averaged (Coleman/MBC) model is only as good as its azimuth sampling: too few azimuths and the average does not remove the rotor’s periodic content, so the Campbell frequencies are biased. VANE’s “thin azimuth coverage” warning is otherwise an empirical judgement; this module replaces it with a calibration curve — how the averaged natural frequencies converge as the azimuth count grows — measured against the densest available sampling as the reference.

Given a dense per-azimuth set, azimuth_density_sweep() sub-samples it to a series of azimuth counts (1, 3, 6, 12, 36, …), re-averages, and reports the natural-frequency error of each coarse model relative to the full-density reference. recommend_azimuth_count() then reads off the smallest azimuth count that brings that error under a tolerance — a data-grounded answer to “how many azimuths are enough” for a given turbine, in place of a hard-coded rule.

class AzimuthConvergence(densities, frequency_error_hz, natural_frequencies_hz, reference_frequencies_hz)[source]

Bases: object

How the averaged-model natural frequencies converge with azimuth count.

Parameters:

densities (npt.NDArray[np.int]) – The azimuth counts evaluated, ascending.
frequency_error_hz (npt.NDArray[np.float64]) – For each density, the maximum natural-frequency difference (Hz) between that coarse averaged model and the full-density reference.
natural_frequencies_hz (npt.NDArray[np.float64]) – The sorted natural frequencies (Hz) at each density, shape (n_density, n_frequencies).
reference_frequencies_hz (npt.NDArray[np.float64]) – The reference (full-density) sorted natural frequencies (Hz).

densities: npt.NDArray[np.int_]

frequency_error_hz: npt.NDArray[np.float64]

natural_frequencies_hz: npt.NDArray[np.float64]

reference_frequencies_hz: npt.NDArray[np.float64]

azimuth_density_sweep(per_azimuth_a, azimuths, *, densities=(1, 3, 6, 12, 36))[source]

Measure how the averaged model’s frequencies converge with azimuth count.

Sub-samples the (azimuth-sorted) per-azimuth matrices to each requested count, takes the mean as the averaged model, and compares its natural frequencies to those of the full-density average (the reference).

Parameters:

per_azimuth_a (npt.ArrayLike) – The frozen-time state matrices, shape (n_azimuth, n, n) (e.g. MBCResult.per_azimuth_a).
azimuths (npt.ArrayLike) – The rotor azimuth of each matrix; used only to order the samples, so any consistent unit works (degrees or radians, e.g. MBCResult.azimuths_deg).
densities (Sequence[int], optional) – Azimuth counts to evaluate; counts above the available number are skipped. Default (1, 3, 6, 12, 36).

Returns:

AzimuthConvergence – The per-density frequencies and their error versus the full-density reference.

Raises:

ValueError – If the matrices are not a consistent (n_azimuth, n, n) stack, the matrices or azimuths are non-finite, the azimuths do not match, a requested density is non-finite or not a whole number, or no requested density is achievable.

Return type:

AzimuthConvergence

recommend_azimuth_count(convergence, *, tolerance_hz)[source]

Return the smallest evaluated azimuth count whose frequency error is within tol.

Reads the convergence curve for the fewest azimuths at which the averaged model’s natural-frequency error (and that of every denser model evaluated) stays at or below tolerance_hz — the data-grounded minimum azimuth coverage.

Parameters:

convergence (AzimuthConvergence) – A sweep from azimuth_density_sweep().
tolerance_hz (float) – The acceptable natural-frequency error (Hz).

Returns:

int – The recommended azimuth count.

Raises:

ValueError – If tolerance_hz is not positive, or no evaluated density meets it (the sampling does not converge within tolerance — use more azimuths).

Return type:

int

A spinning rotor makes the linearized dynamics \(\dot{\mathbf x} = \mathbf A(\psi) \mathbf x\) periodic in the azimuth \(\psi = \Omega t\) with period \(T = 2\pi/\Omega\), not time-invariant. The multi-blade (Coleman) transform removes that periodicity only for an isotropic rotor; for an anisotropic system — a two-bladed rotor, or a floating turbine whose mooring/hydrodynamics break the rotational symmetry — the azimuth-averaged model is an approximation whose error this module quantifies and replaces.

Floquet theory writes each solution as \(\mathbf x(t) = e^{\lambda t}\mathbf p(t)\) with \(\mathbf p\) periodic; the Floquet exponents \(\lambda\) are the true modal eigenvalues of the periodic system and \(\mathbf p(t) = \sum_m \mathbf p_m e^{i m \Omega t}\) carries the harmonic mode-shape components. Two independent routes are provided:

Hill’s method (floquet_modes()): expand \(\mathbf A(\psi) = \sum_n \mathbf A_n e^{i n\psi}\) and solve the eigenproblem of the Hill matrix with blocks \(\mathbf H_{kj} = \mathbf A_{k-j} - i k\Omega\,\delta_{kj}\mathbf I\); the principal exponents are the eigenvalues whose eigenvectors concentrate in the fundamental (\(m=0\)) harmonic, and the blocks give \(\mathbf p_m\).
The monodromy matrix (monodromy_exponents()): integrate the state-transition matrix over one period (piecewise-constant / matrix-exponential product); its eigenvalues are the Floquet multipliers \(\mu\), and \(\lambda = \ln\mu / T\). An independent cross-check of Hill.

For an isotropic rotor (every \(\mathbf A(\psi)\) equal) both reduce to the ordinary eigenvalues of that constant matrix, so the Floquet result degrades gracefully to the averaged-model answer; the gap between them is the anisotropy error (averaging_error()).

HILL_UNIFORM_RTOL = 0.001: Relative tolerance on the azimuth intervals for Hill’s method. The Fourier coefficients of A(psi) come from the equal-weight discrete transform, which is exact only on a uniform grid, so every interval must equal the mean interval to this fraction of it (plus a 1e-9 rad absolute floor).

class FloquetSolution(exponents, natural_frequencies_hz, damping_ratios, harmonics, harmonic_mode_shapes, rotor_speed)[source]

Bases: object

The Floquet modes of a linear time-periodic system.

Parameters:

exponents (npt.NDArray[np.complex128]) – The principal Floquet exponents \(\lambda\) (one per state), sorted by ascending natural frequency. Selected as the Hill eigenvalues that concentrate in the fundamental (\(m=0\)) harmonic, one per distinct Floquet solution (harmonic-shifted copies \(\lambda + ik\Omega\) of a kept exponent are skipped), so a near-time-invariant system recovers the ordinary eigenvalues unfolded (constant \(A\) gives eig(A) exactly) — unlike monodromy_exponents(), whose imaginary part is known only modulo \(\Omega\).
natural_frequencies_hz (npt.NDArray[np.float64]) – |lambda| / 2pi for each exponent.
damping_ratios (npt.NDArray[np.float64]) – -Re(lambda) / |lambda| for each exponent.
harmonics (npt.NDArray[np.int]) – The harmonic indices m of the mode-shape blocks, from -n_harmonics to +n_harmonics.
harmonic_mode_shapes (npt.NDArray[np.complex128]) – The periodic mode-shape components p_m, shape (n_harmonics_total, n_dof, n_modes); [harmonics == 0] is the fundamental (mean) mode shape.
rotor_speed (float) – The rotor speed \(\Omega\) (rad/s) used.

exponents: npt.NDArray[np.complex128]

natural_frequencies_hz: npt.NDArray[np.float64]

damping_ratios: npt.NDArray[np.float64]

harmonics: npt.NDArray[np.int_]

harmonic_mode_shapes: npt.NDArray[np.complex128]

rotor_speed: float

averaging_error(per_azimuth_a, azimuths, rotor_speed, *, n_harmonics=4)[source]

Return the azimuth-averaging error: max frequency gap (Hz) Floquet vs averaged.

Compares the Floquet natural frequencies to those of the azimuth-averaged model (the eigenvalues of the mean of per_azimuth_a, which is what the averaged-LTI / MBC path uses). Zero for an isotropic rotor; it grows with anisotropy — the quantity that says when the averaged Campbell diagram is untrustworthy.

Parameters:

per_azimuth_a (npt.ArrayLike) – As for floquet_modes().
azimuths (npt.ArrayLike) – As for floquet_modes().
rotor_speed (float) – As for floquet_modes().
n_harmonics (int) – As for floquet_modes().

Returns:

float – The maximum absolute difference (Hz) between matched Floquet and averaged natural frequencies.

Raises:

ValueError – As floquet_modes(); in particular the azimuths must be near-uniform (relative HILL_UNIFORM_RTOL), because the Floquet frequencies come from Hill’s method.

Return type:

floquet_modes(per_azimuth_a, azimuths, rotor_speed, *, n_harmonics=4)[source]

Compute the Floquet modes of an LTP system by Hill’s harmonic-balance method.

Parameters:

per_azimuth_a (Sequence[npt.NDArray[np.float64]]) – The frozen-time state matrices \(\mathbf A(\psi_k)\), one per azimuth (e.g. MBCResult.per_azimuth_a with retain_per_azimuth=True).
azimuths (Sequence[float]) – The rotor azimuth (rad) of each matrix, spanning one revolution.
rotor_speed (float) – The rotor speed \(\Omega\) (rad/s); must be positive.
n_harmonics (int, optional) – Harmonic truncation order M; the Hill blocks need Fourier coefficients up to \(2M\), so the near-uniform azimuth sweep (see Notes) must have len(per_azimuth_a) >= 4*n_harmonics + 1 samples so those coefficients are resolved without aliasing.

Returns:

FloquetSolution – The principal Floquet exponents, their frequencies/damping, and the harmonic mode-shape components.

Raises:

ValueError – If rotor_speed is not positive, the matrices are not square and consistent, the azimuth sweep is not near-uniform (see Notes; the message names the worst interval and its relative deviation), or it has too few samples to resolve the Hill coefficients for n_harmonics without aliasing.

Warns:

RuntimeWarning – If the selected exponents do not reproduce the monodromy multipliers (\(e^{\lambda T}\), compared modulo \(i\Omega\)) to within \(10^{-2}\Omega\) — the harmonic truncation or azimuth sampling is too coarse for this system.

Return type:

FloquetSolution

Notes

Limitation: near-uniform azimuths only. The Fourier coefficients of \(\mathbf A(\psi)\) are computed with the equal-weight discrete transform, which is exact only on a uniform grid. Every azimuth interval, including the one that closes the revolution, must equal the mean interval within a relative HILL_UNIFORM_RTOL (1e-3); otherwise ValueError is raised. OpenFAST linearizes at the time steps nearest the requested azimuths, so a delivered grid is uneven unless the time step is commensurate with the azimuth spacing (commensurate_time_step()) and the rotor runs at its trimmed speed. Analyse an uneven delivered grid with monodromy_exponents(), which weights each matrix by its own interval and accepts any distinct azimuths (its frequencies are known only modulo \(\Omega\)). averaging_error() calls this function and has the same restriction.

Every Floquet solution appears in the Hill spectrum as a family of copies \(\lambda + ik\Omega\). Exactly one representative per distinct solution is kept: candidates are walked in descending fundamental (\(m=0\)) energy and a candidate that is a harmonic-shifted copy of an already-kept exponent (same exponent modulo \(i\Omega\) and the same eigenvector shifted by \(k\) blocks) is skipped. Inside a parametric-resonance tongue (real negative multipliers, \(\operatorname{Im}\lambda \equiv \Omega/2\)) the conjugate of an exponent is such a copy, so both tongue families — including an unstable one — are kept; distinct solutions sharing a multiplier (an isotropic mode at exactly \(\Omega/2\)) are both kept.

monodromy_exponents(per_azimuth_a, azimuths, rotor_speed)[source]

Return the Floquet exponents via the monodromy matrix (independent of Hill).

Integrates the state-transition matrix over one revolution as a product of matrix exponentials over the (piecewise-constant) azimuth intervals; the eigenvalues of that monodromy matrix are the Floquet multipliers \(\mu\), and the exponents are \(\ln\mu / T\).

Note

The multiplier \(\mu = e^{\lambda T}\) is invariant under \(\lambda \mapsto \lambda + i k\Omega\), so this matrix determines the exponent’s real part (damping/growth rate) exactly but its imaginary part (frequency) only modulo \(\Omega\): the principal branch of the logarithm folds it into the fundamental strip \((-\Omega/2, \Omega/2]\). A mode whose damped frequency exceeds \(\Omega/2\) is therefore reported aliased (e.g. a 0.8 Hz mode with a 1 Hz rotor comes back at 0.2 Hz). Use floquet_modes() (Hill) for the unfolded frequencies; this helper is an exact cross-check of the damping and of frequencies within the strip.

Parameters:

per_azimuth_a (Sequence[npt.NDArray[np.float64]]) – The frozen-time state matrices, one per azimuth.
azimuths (Sequence[float]) – The rotor azimuth (rad) of each matrix.
rotor_speed (float) – The rotor speed \(\Omega\) (rad/s); must be positive.

Returns:

npt.NDArray[np.complex128] – The Floquet exponents (real part exact; imaginary part folded into the principal strip \((-\Omega/2, \Omega/2]\)), sorted by natural frequency.

Raises:

ValueError – If rotor_speed is not positive and finite, the matrices are non-finite or inconsistently shaped, or the azimuths are non-finite or not distinct (after wrapping into [0, 2pi)).

Return type:

npt.NDArray[np.complex128]

Azimuth averaging

See Azimuth averaging for the workflow.

The azimuth-averaged (Coleman/MBC) model of a rotating turbine is a weighted mean of the fixed-frame state matrices \(\mathbf A(\psi_\ell)\) sampled at the azimuths a linearization actually delivered. Those azimuths are rarely uniform: each snapshot is taken at the first time step at or past its target azimuth. This module provides the building blocks for treating that mean exactly and for auditing it.

Quadrature. interval_weights() gives the weights of the periodic piecewise-linear interpolant of the samples (the exact mean of that interpolant), and weight_kernel() their discrete Fourier transform \(W(h)=\sum_\ell w_\ell e^{\,jh\psi_\ell}\), the aliasing kernel of the grid.
Harmonics. fit_harmonics() represents the samples by a harmonic model \(\mathbf A(\psi)=\sum_h \mathbf A_h e^{\,jh\psi}\). With the default interpolating trigonometric fit the error of any weighted mean of the samples is exactly \(\mathbf E=\sum_h[W_S(h)-W_{\mathrm{ref}}(h)]\mathbf A_h\) (grid_error_matrix()).
The rotor-azimuth state. locate_azimuth_state() finds the ElastoDyn generator-azimuth position (DOF_GeAz) and rotor-speed states from the state descriptions. For a linearization about a periodic orbit the time derivative of that orbit (the orbit tangent, whose azimuth component is one) solves the linearized equations, so one Floquet exponent is exactly zero. azimuth_consistency() tests this from the averaged model alone: the averaged azimuth eigenvalue plus its second-order sideband correction (sideband_correction()) must vanish.
Azimuth treatments. pin_azimuth() replaces each sample by \(\mathbf A(\psi)(\mathbf I-\boldsymbol\xi\mathbf e_{\mathrm{az}}^T)\), which makes the tangent \(\boldsymbol\xi\) an exact null vector of every sample and, when \(\boldsymbol\xi\) is the right eigenvector of the reference mean (azimuth_tangent()), leaves every other reference eigenvalue unchanged. The simpler zero_azimuth_column() and delete_azimuth_state() are kept for comparison; they also remove the zero-eigenvalue artefact but bias the reference, because the mean of the azimuth column is physical (the rotation of the gravity-sagged rotor, cancelled in an exact linearization by the cyclic blade coupling).

The per-branch error budget built on these pieces is in vane.modal.averaging_error_estimate. Everything here is pure NumPy/SciPy and takes azimuths in radians.

class AzimuthConsistency(eigenvalue, correction, exponent, index, azimuth_share, condition, stiffness, speed_damping, tolerance, consistent, pair_indices, pair_eigenvalues, pair_exponents, residual_exponent, residual_stiffness, absolute_consistent, scale_tolerance, branch_risks, assessment)[source]

Bases: object

Result of the azimuth (periodic-orbit) consistency test.

The azimuth position and rotor-speed states form a pair of modes, condensed \(s^2-bs-\kappa=0\). Both modes are tested: their sideband-corrected exponents \(\gamma_{1,2}\) estimate the two Floquet exponents, one of which is exactly zero for a linearization about a periodic orbit.

Parameters:

eigenvalue (complex) – The averaged eigenvalue \(\lambda\) of the growing mode of the pair, the one whose exponent has the larger real part (1/s).
correction (complex) – Its sideband correction \(\widehat{\Delta\lambda}\).
exponent (complex) – \(\gamma_1=\lambda+\widehat{\Delta\lambda}\), the growing exponent of the pair. In a saddle (\(\kappa>0\)) this is the unstable root, not the stable one, whatever their azimuth shares.
index (int) – Index of that mode in the eigenbasis of the reference mean.
azimuth_share (float) – Participation share of the azimuth position state in that mode.
condition (float) – Eigenvalue condition number of that mode (large for the near-Jordan pair).
stiffness (float) – \(\kappa\), the azimuth stiffness of the static condensation of the reference mean onto (azimuth, rotor speed); nan without the speed state.
speed_damping (float) – \(b\), the rotor-speed damping of that condensation (1/s); nan without the speed state.
tolerance (float) – Absolute tolerance on the residual exponent (1/s), kept for comparison.
consistent (bool) – assessment == "consistent".
pair_indices (tuple[int, int]) – Indices of the two modes of the pair, growing first.
pair_eigenvalues (tuple[complex, complex]) – Their averaged eigenvalues.
pair_exponents (tuple[complex, complex]) – Their sideband-corrected exponents \((\gamma_1,\gamma_2)\), \(\operatorname{Re}\gamma_1\ge\operatorname{Re}\gamma_2\).
residual_exponent (float) – \(r=\min(|\gamma_1|,|\gamma_2|)\), the distance of the pair from an exact zero exponent (1/s).
residual_stiffness (float) – \(\kappa_r=-\operatorname{Re}(\gamma_1\gamma_2)\), the azimuth stiffness implied by the exponents (1/s^2); zero for a consistent linearization.
absolute_consistent (bool) – residual_exponent <= tolerance: a fixed absolute-tolerance test.
scale_tolerance (float) – The dimensionless tolerance :math:` au` of the scaled test.
branch_risks (tuple[BranchAzimuthRisk, ...]) – The decay and coalescence ratios of every assessed branch.
assessment (str) – "consistent", "inconsistent-but-harmless" or "inconsistent-and-risky" (see azimuth_consistency()).

eigenvalue: complex

correction: complex

exponent: complex

index: int

azimuth_share: float

condition: float

stiffness: float

speed_damping: float

tolerance: float

consistent: bool

pair_indices: tuple[int, int]

pair_eigenvalues: tuple[complex, complex]

pair_exponents: tuple[complex, complex]

residual_exponent: float

residual_stiffness: float

absolute_consistent: bool

scale_tolerance: float

branch_risks: tuple[BranchAzimuthRisk, ...]

assessment: Literal['consistent', 'inconsistent-but-harmless', 'inconsistent-and-risky']

property growth_rate: float

Return \(\operatorname{Re}\gamma_1\), the largest real part of the pair.

With an open-loop rotor whose aerodynamic torque rises with speed (\(b>0\)) this is the physical rotor-speed divergence, not a defect; the assessment therefore uses the residual, not the growth rate.

property speed_damping_exponent: float: Return \(b_\gamma=\operatorname{Re}(\gamma_1+\gamma_2)\) (1/s).

property pendulum_frequency: float

Return the azimuth pendulum frequency \(\sqrt{-\kappa-b^2/4}\) (rad/s).

A negative stiffness, for example created by aliasing on a coarse grid, makes the azimuth an oscillator that can hybridise with a platform branch near this frequency. Zero for a real pair or an unknown condensation.

property residual_pendulum_frequency: float

Return \(|\operatorname{Im}\gamma_1|\), the residual pair frequency.

Non-zero only when the residual makes the azimuth pair oscillatory.

property worst_branch: BranchAzimuthRisk | None

Return the assessed branch with the largest coalescence ratio.

Returns:: BranchAzimuthRisk or None – None when no branch was assessed.

class AzimuthStates(position, speed=None)[source]

Bases: object

Positions of the rotor-azimuth position and rotor-speed states.

Parameters:

position (int) – 0-based index of the rotor-azimuth position state (ElastoDyn DOF_GeAz).
speed (int or None, optional) – 0-based index of its rate, the rotor-speed state, when known.

position: int

speed: int | None = None

class BranchAzimuthRisk(index, eigenvalue, decay_ratio, coalescence_ratio, risky)[source]

Bases: object

How strongly the azimuth residual can contaminate one branch.

Parameters:

index (int) – Index of the branch in the eigenbasis of the reference mean.
eigenvalue (complex) – Its reference eigenvalue \(\lambda_j=-\sigma_j+j\omega_j\) (1/s).
decay_ratio (float) – \(\nu_j=r/\sigma_j\), the residual exponent over the branch decay rate (inf for a branch that does not decay).
coalescence_ratio (float) – \(\mu_j=|\kappa_r|/(\omega_j^2+b_\gamma^2/4)\), the residual azimuth stiffness over the coalescence threshold of the branch.
risky (bool) – Both ratios exceed the scale tolerance.

index: int

eigenvalue: complex

decay_ratio: float

coalescence_ratio: float

risky: bool

class EigenBasis(values, left, right, condition)[source]

Bases: object

Biorthonormal eigentriples of a state matrix.

Parameters:

values (npt.NDArray[np.complex128]) – Every eigenvalue \(\lambda_k\) (conjugates included), in solver order.
left (npt.NDArray[np.complex128]) – Left eigenvectors as columns, scaled so that \(\mathbf u_k^H\mathbf v_k=1\).
right (npt.NDArray[np.complex128]) – Unit-norm right eigenvectors as columns.
condition (npt.NDArray[np.float64]) – Eigenvalue condition numbers \(1/|\hat{\mathbf u}_k^H\mathbf v_k|\) of the unit-norm pair.

values: npt.NDArray[np.complex128]

left: npt.NDArray[np.complex128]

right: npt.NDArray[np.complex128]

condition: npt.NDArray[np.float64]

participation()[source]

Return the participation magnitudes \(|\bar u_{sk}v_{sk}|\).

Returns:: npt.NDArray[np.float64] – Shape (n_states, n_modes).
Return type:: npt.NDArray[np.float64]

nearest(eigenvalue)[source]

Return the index of the eigenvalue closest to eigenvalue.

Parameters:: eigenvalue (complex) – Target eigenvalue (1/s).
Returns:: int – Index into values.
Return type:: int

class HarmonicModel(azimuths, reference_weights, reference_mean, coefficients, method, interpolating, nyquist_order=None, blades=None)[source]

Bases: object

Harmonic representation \(\mathbf A(\psi)=\sum_h\mathbf A_h e^{jh\psi}\).

Parameters:

azimuths (npt.NDArray[np.float64]) – The delivered azimuths (rad, wrapped into [0, 2pi)) the model was fitted to.
reference_weights (npt.NDArray[np.float64]) – The interval weights of those azimuths (the reference quadrature rule).
reference_mean (npt.NDArray[np.float64]) – The reference mean \(\sum_\ell w_\ell^{\mathrm{ref}}\mathbf A(\psi_\ell)\) computed from the samples.
coefficients (dict[int, npt.NDArray[np.complex128]]) – \(\mathbf A_h\) for every order present, with \(\mathbf A_{-h}=\overline{\mathbf A_h}\).
method (str) – "trigonometric" (least-squares trigonometric series) or "piecewise_linear" (exact Fourier coefficients of the periodic piecewise-linear interpolant).
interpolating (bool) – Whether the model reproduces every sample exactly (a square trigonometric design). Only an interpolating model makes grid_error_matrix() exact.
nyquist_order (int or None) – The order represented by its cosine only (half the sample count of an interpolating fit to an even number of samples), else None.
blades (int or None) – When set, only orders that are multiples of blades were fitted.

azimuths: npt.NDArray[np.float64]

reference_weights: npt.NDArray[np.float64]

reference_mean: npt.NDArray[np.float64]

coefficients: dict[int, npt.NDArray[np.complex128]]

method: str

interpolating: bool

nyquist_order: int | None = None

blades: int | None = None

property orders: npt.NDArray[np.int_]: Return every order present (negative and positive), ascending.

property max_order: int: Return the highest order present (including a cosine-only Nyquist order).

property resolved_order: int: Return the highest order whose cosine and sine are both resolved.

property mean: npt.NDArray[np.float64]: Return the zeroth harmonic \(\mathbf A_0\) (real).

evaluate(azimuths)[source]

Evaluate the model at the given azimuths.

Parameters:: azimuths (npt.ArrayLike) – Azimuths in radians (any finite values).
Returns:: npt.NDArray[np.float64] – The model matrices, shape (n, *sample_shape).
Return type:: npt.NDArray[np.float64]

uniform_mean(count, start=0.0)[source]

Return the model mean over a uniform count-grid starting at start.

Parameters:

count (int) – Number of uniform azimuths.
start (float, optional) – First azimuth in radians.

Returns:

npt.NDArray[np.float64] – \(\mathbf A_0+\sum_{h\neq0,\ N\mid h}\mathbf A_h e^{jh\psi_0}\), the exact equal-weight mean of the model on that grid.

Return type:

npt.NDArray[np.float64]

class TowerPassageFit(orders, magnitudes, decay, amplitude, log_r2, condensed)[source]

Bases: object

Fit of the tower-passage law to the azimuth-column harmonics.

Parameters:

orders (npt.NDArray[np.int]) – The fitted orders (resolved multiples of the blade count).
magnitudes (npt.NDArray[np.float64]) – \(|c_h|\) at those orders.
decay (float) – \(\rho\), the fitted decay per harmonic order.
amplitude (float) – \(A_B\), the fitted magnitude at the blade order.
log_r2 (float) – Coefficient of determination of the fit in \(\log|c_h|\).
condensed (bool) – Whether \(c_h\) is the condensed azimuth stiffness harmonic \(\boldsymbol\ell^T\mathbf A_h\boldsymbol\xi\) (rotor-speed state known) or the azimuth-column norm \(\|\mathbf A_h\mathbf e_{\mathrm{az}}\|\).

orders: npt.NDArray[np.int_]

magnitudes: npt.NDArray[np.float64]

decay: float

amplitude: float

log_r2: float

condensed: bool

azimuth_consistency(model, rotor_speed, azimuth, *, tolerance=0.0001, basis=None, max_order=None, branches=None, scale_tolerance=0.01)[source]

Test whether the samples are a linearization about a periodic orbit.

Parameters:

model (HarmonicModel) – Harmonic model of the samples ("piecewise_linear" recommended).
rotor_speed (float) – Rotor speed \(\Omega\) in rad/s.
azimuth (AzimuthStates or int) – The rotor-azimuth states (see locate_azimuth_state()). The rotor-speed index is needed for the condensed stiffness and damping.
tolerance (float, optional) – Absolute tolerance on the residual exponent in 1/s, reported as absolute_consistent. Default 1e-4. It decides the assessment only when no branch is assessed.
basis (EigenBasis or None, optional) – Eigentriples of model.reference_mean if already computed.
max_order (int or None, optional) – Highest harmonic order in the sideband sum; default every order.
branches (Sequence[int] or None, optional) – Indices (into the eigenbasis of the reference mean) of the branches the residual is assessed against. Default every oscillatory mode (positive imaginary part) outside the pair.
scale_tolerance (float, optional) – Dimensionless tolerance \(\tau\) of the decay and coalescence ratios. Default 0.01. estimate_averaging_error() uses its damping tolerance, as a fraction.

Returns:

AzimuthConsistency – Both exponents of the azimuth/speed pair (the growing one first), the residual exponent and stiffness, the per-branch ratios and the graded assessment.

Raises:

ValueError – If the model is not of square matrices, rotor_speed, tolerance or scale_tolerance is invalid, or an index is out of range.

Return type:

AzimuthConsistency

Notes

The orbit tangent of an autonomous system linearized about a periodic orbit is a periodic solution of the linear time-periodic model, so one Floquet exponent is exactly zero. The averaged model then has an eigenvalue of second order in the harmonics whose sideband correction cancels it. Both modes of the azimuth/rotor-speed pair are corrected, giving \(\gamma_{1,2}\). In the condensation \(s^2-bs-\kappa=0\) their sum is the speed damping \(b_\gamma\) and their product is \(-\kappa_r\), so the defect is the residual stiffness \(\kappa_r=-\gamma_1\gamma_2\) (zero when one root vanishes) and the residual exponent \(r=\min|\gamma_{1,2}|\). A positive \(b\) with \(\kappa_r=0\) is the physical open-loop rotor-speed divergence and is not a defect.

The residual matters only for the branches it can reach. For a branch \(\lambda_j=-\sigma_j+j\omega_j\) two ratios are formed,

\[\nu_j=\frac{r}{\sigma_j},\qquad \mu_j=\frac{|\kappa_r|}{\omega_j^2+b_\gamma^2/4}.\]

\(\nu_j\le\tau\) means the residual root is slower than the branch decay by \(1/\tau\): even fully mixed into the branch it would change the decay rate by at most \(\tau\sigma_j\). \(\mu_j\) is the coalescence condition of the two-state azimuth model: the azimuth pendulum, of decay rate \(|b|/2\), can be tuned to the branch frequency only when the azimuth stiffness reaches \(\omega_j^2+b^2/4\). \(\mu_j\) is the share of that threshold the residual consumes on its own, and \(\sqrt{\mu_j}\) is the natural frequency of the residual pair relative to it. The assessment is "consistent" when \(\nu_j\le\tau\) for every branch; "inconsistent-and-risky" when some branch has both \(\nu_j>\tau\) and \(\mu_j>\tau\) (the residual is neither slow against the branch decay nor a decade below it in frequency, for \(\tau=0.01\)); "inconsistent-but-harmless" otherwise. Without branches the absolute test decides between the first and the last. The test detects but does not locate the defect (for example a trim controller still acting during the linearization revolution).

azimuth_mean(azimuths, matrices, *, rule='interval')[source]

Return the azimuth mean of a stack of sampled matrices.

Parameters:

azimuths (npt.ArrayLike) – Delivered azimuths in radians, one per sample.
matrices (npt.ArrayLike) – Stack of samples, shape (n_azimuth, ...) (state, input or output matrices).
rule ({"interval", "arithmetic"}, optional) – "interval" (default) uses interval_weights(); "arithmetic" the plain sample mean that the MBC transform applies.

Returns:

npt.NDArray[np.float64] – The weighted mean, with the shape of one sample.

Raises:

ValueError – If the inputs are inconsistent or the rule is unknown.

Return type:

npt.NDArray[np.float64]

azimuth_tangent(mean_matrix, azimuth, *, n_samples=None)[source]

Return the orbit-tangent estimate \(\boldsymbol\xi\) from an averaged model.

Parameters:

mean_matrix (npt.ArrayLike) – The reference (azimuth-averaged) state matrix of a dense grid.
azimuth (AzimuthStates or int) – The rotor-azimuth position state.
n_samples (int or None, optional) – Number of azimuths that formed the mean. Below 18 a warning is issued: the neutral direction of a coarse mean is itself contaminated by aliasing.

Returns:

npt.NDArray[np.float64] – The real right eigenvector of the mode with the largest azimuth-state share, normalised to \(\xi_{\mathrm{az}}=1\).

Raises:

ValueError – If the matrix is invalid or the azimuth index is out of range.

Warns:

RuntimeWarning – If n_samples is below 18, or the azimuth eigenvalue is complex (an oscillatory azimuth pair; the real part of its eigenvector is returned and pinning then preserves the reference only to the size of its imaginary part).

Return type:

npt.NDArray[np.float64]

delete_azimuth_state(matrices, azimuth)[source]

Delete the rotor-azimuth position state (row and column).

Parameters:

matrices (npt.ArrayLike) – One state matrix (n, n) or a stack (n_azimuth, n, n).
azimuth (AzimuthStates or int) – The rotor-azimuth position state.

Returns:

npt.NDArray[np.float64] – Matrices of size n - 1. The rotor-speed state is kept as a first-order state, so the [q2, q2dot, q1] pairing no longer holds.

Raises:

ValueError – If the matrices are not square or the index is out of range.

Return type:

npt.NDArray[np.float64]

Notes

This is the conventional Campbell practice of dropping the zero-frequency generator mode. Its eigenvalues (and Floquet multipliers) are exactly those of zero_azimuth_column() without the zero, because a zero column makes the matrix block-triangular. It therefore biases the reference in the same way; see zero_azimuth_column().

eigen_basis(matrix)[source]

Return the biorthonormal eigentriples of a square state matrix.

Parameters:: matrix (npt.ArrayLike) – Square, finite state matrix.
Returns:: EigenBasis – Eigenvalues with left and right eigenvectors, u_k^H v_k = 1.
Raises:: ValueError – If the matrix is not square and finite, or an eigenvalue is defective (its left and right eigenvectors are orthogonal to working precision).
Return type:: EigenBasis

fit_harmonics(azimuths, matrices, *, method='trigonometric', max_order=None, blades=None)[source]

Fit a harmonic model \(\mathbf A(\psi)=\sum_h\mathbf A_h e^{jh\psi}\).

Parameters:

azimuths (npt.ArrayLike) – Delivered azimuths in radians, one per sample (any order).
matrices (npt.ArrayLike) – Sample stack, shape (n_azimuth, ...).
method ({"trigonometric", "piecewise_linear"}, optional) – "trigonometric" (default) solves the trigonometric design by least squares. With the default max_order it is square, orders 0..(M-1)//2 plus the cosine of order M/2 for an even sample count M, so the model interpolates every sample and the sampling-error identity of grid_error_matrix() holds exactly. "piecewise_linear" returns the exact Fourier coefficients of the periodic piecewise-linear interpolant of the samples; its \(\mathbf A_0\) equals the interval-weighted mean, which makes it the natural model for the sideband (periodicity) estimate.
max_order (int or None, optional) – Highest harmonic order. Default (M-1)//2 (with the Nyquist cosine for the trigonometric fit to an even M). A trigonometric fit with 2*max_order + 1 > M is rejected.
blades (int or None, optional) – Keep only orders that are multiples of blades (the content an isotropic blades-bladed rotor leaves after MBC). The trigonometric fit is then a least-squares fit and does not interpolate.

Returns:

HarmonicModel – The fitted model, with the reference (interval) weights and mean.

Raises:

ValueError – If the inputs are inconsistent, method is unknown, max_order or blades is not a positive integer, the design has more unknowns than samples, or it is ill-conditioned.

Return type:

HarmonicModel

grid_error_matrix(model, azimuths, weights=None)[source]

Return the error of a grid’s mean relative to the reference mean.

Parameters:

model (HarmonicModel) – Harmonic model of the delivered samples.
azimuths (npt.ArrayLike) – The azimuths (rad) of the grid whose mean is assessed: a subset of the delivered azimuths (a measured sub-grid) or any hypothetical grid (a design).
weights (npt.ArrayLike or None, optional) – The grid’s quadrature weights; default its interval_weights().

Returns:

npt.NDArray[np.float64] – \(\mathbf E=\sum_h[W_{\mathrm{grid}}(h)-W_{\mathrm{ref}}(h)]\mathbf A_h\).

Return type:

npt.NDArray[np.float64]

Notes

Any weighted mean of the samples is \(\sum_h W(h)\mathbf A_h\) exactly when the model interpolates the samples, so for a sub-grid of the delivered azimuths and an interpolating model this equals \(\sum_\ell(w_\ell^{S}-w_\ell^{\mathrm{ref}}) \mathbf A(\psi_\ell)\) to rounding. The zeroth harmonic cancels because \(W(0)=1\) for every consistent rule. On a uniform \(N\)-grid \(W(h)\) vanishes unless \(N\mid h\) (the familiar aliasing rule); on a non-uniform grid it leaks at every order, which this form keeps. For a grid that is not a subset of the samples the result is a model-based prediction that ignores orders above HarmonicModel.max_order.

interval_weights(azimuths)[source]

Return the interval (periodic trapezoidal) weights of an azimuth grid.

Parameters:: azimuths (npt.ArrayLike) – Delivered azimuths in radians, any order, distinct modulo \(2\pi\).
Returns:: npt.NDArray[np.float64] – One weight per azimuth, in the input order, summing to one. Applied to the samples they give the exact revolution mean of the periodic piecewise-linear interpolant.
Raises:: ValueError – If the azimuths are empty, non-finite, duplicated after wrapping, or leave a gap larger than half a revolution (a single azimuth always does).
Return type:: npt.NDArray[np.float64]

Notes

With the azimuths sorted, \(g_\ell=\psi_{\ell+1}-\psi_\ell\) the periodic gaps and \(g_0 \equiv g_M\),

\[w_\ell = \frac{g_{\ell-1}+g_\ell}{4\pi},\]

which reduces to \(1/M\) on a uniform grid.

locate_azimuth_state(state_descriptions, *, ndof2=None)[source]

Locate the rotor-azimuth position and rotor-speed states from descriptions.

Parameters:

state_descriptions (Sequence[str]) – State descriptions in matrix order (e.g. MBCResult.state_descriptions).
ndof2 (int or None, optional) – Number of second-order DOFs of the [q2, q2dot, q1] layout. Used to place the rotor-speed state at position + ndof2 when no velocity description of the generator DOF is present.

Returns:

AzimuthStates – The position index and, when found, the speed index.

Raises:

ValueError – If no state, or more than one non-velocity state, carries the generator azimuth token DOF_GeAz, or ndof2 is inconsistent with the layout.

Return type:

AzimuthStates

pin_azimuth(matrices, tangent, azimuth)[source]

Apply tangent-pinned averaging to one matrix or a stack of samples.

Each matrix is replaced by \(\mathbf A'=\mathbf A(\mathbf I-\boldsymbol\xi\mathbf e_{\mathrm{az}}^T)\).

Parameters:

matrices (npt.ArrayLike) – One state matrix (n, n) or a stack (n_azimuth, n, n).
tangent (npt.ArrayLike) – Tangent \(\boldsymbol\xi\) of length n; it is rescaled so that its azimuth component is one.
azimuth (AzimuthStates or int) – The rotor-azimuth position state.

Returns:

npt.NDArray[np.float64] – The pinned matrices, same shape as matrices. Only the azimuth column changes, to \(\mathbf A\mathbf e_{\mathrm{az}}-\mathbf A\boldsymbol\xi\).

Raises:

ValueError – If shapes disagree, the inputs are non-finite, or the tangent’s azimuth component is zero.

Return type:

npt.NDArray[np.float64]

Notes

\(\mathbf I-\boldsymbol\xi\mathbf e_{\mathrm{az}}^T\) is an oblique projector, so \(\mathbf A'(\psi)\boldsymbol\xi=\mathbf 0\) for every sample: every sub-grid mean has an exact zero eigenvalue and the periodic model an exact unit Floquet multiplier. If \(\boldsymbol\xi\) is a right eigenvector of the reference mean with eigenvalue \(\lambda_{\mathrm{az}}\), the pinned mean is \(\bar{\mathbf A}-\lambda_{\mathrm{az}}\boldsymbol\xi\mathbf e_{\mathrm{az}}^T\) and, by Brauer’s theorem, keeps every other reference eigenvalue unchanged.

sideband_correction(model, basis, index, rotor_speed, *, max_order=None)[source]

Return the second-order sideband (periodicity) correction of one mode.

Parameters:

model (HarmonicModel) – Harmonic model of the samples (the "piecewise_linear" fit is consistent with the interval-weighted reference).
basis (EigenBasis) – Eigentriples of the reference mean.
index (int) – Mode index into basis.values.
rotor_speed (float) – Rotor speed \(\Omega\) in rad/s.
max_order (int or None, optional) – Highest harmonic order included; default every order of the model.

Returns:

complex – \(\widehat{\Delta\lambda}_j=\sum_{h\neq0}\sum_k \frac{(\mathbf u_j^H\mathbf A_{-h}\mathbf v_k) (\mathbf u_k^H\mathbf A_h\mathbf v_j)}{\lambda_j+jh\Omega-\lambda_k}\), the estimate of the Floquet exponent minus the averaged eigenvalue. Every mode is retained in the sum: truncating it to the modes nearest in detuning is not admissible.

Raises:

ValueError – If rotor_speed is not positive or index is out of range.

Return type:

complex

subgrid_weights(azimuths, indices, *, rule='interval')[source]

Return full-length weights of a sub-grid of the delivered azimuths.

Parameters:

azimuths (npt.ArrayLike) – All delivered azimuths in radians.
indices (Sequence[int] or npt.ArrayLike) – Positions (into azimuths) of the samples that form the sub-grid.
rule ({"interval", "arithmetic"}, optional) – "interval" weights the sub-grid by its own interval_weights(); "arithmetic" gives each of its samples 1/len(indices).

Returns:

npt.NDArray[np.float64] – A weight vector aligned with azimuths, zero off the sub-grid, summing to one.

Raises:

ValueError – If indices is empty, out of range or repeated, or rule is unknown, or the sub-grid is invalid for interval_weights().

Return type:

npt.NDArray[np.float64]

tower_passage_decay(model, azimuth, *, blades=3)[source]

Fit the tower-passage law to the harmonics of the azimuth column.

Parameters:

model (HarmonicModel) – Harmonic model of the delivered samples (the azimuth column as delivered, not pinned or zeroed).
azimuth (AzimuthStates or int) – The rotor-azimuth states. With the rotor-speed state the condensed harmonics \(c_h=\boldsymbol\ell^T\mathbf A_h\boldsymbol\xi\) are fitted, otherwise the column norms \(\|\mathbf A_h\mathbf e_{\mathrm{az}}\|\).
blades (int, optional) – Blade count \(B\); only its multiples are fitted. Default 3.

Returns:

TowerPassageFit – \(|c_h|=A_B\,(h/B)\,\rho^{\,h-B}\) fitted by least squares in \(\log\) over the resolved multiples of \(B\).

Raises:

ValueError – If the model is not of square matrices, blades is not a positive integer, the condensation is singular, or fewer than two blade multiples are resolved with non-zero content.

Return type:

TowerPassageFit

Notes

A tower passage of peak deficit \(\delta\) and harmonic decay \(\rho\) makes the frozen-azimuth derivative of the rotor loads, which is the azimuth column, carry \(|c_h|\propto h\rho^{h-1}\): the derivative of a localised bump whose Fourier coefficients fall as \(\rho^h\). Every other load harmonic of the rotor comes from the same localised inflow, so \(\rho\) sets the decay above the resolved orders that azimuth_count_table() uses when a branch’s own sensitivity does not decay.

uniform_azimuths(count, start=0.0)[source]

Return a uniform grid of count azimuths (rad) starting at start.

Parameters:

count (int) – Number of azimuths; must be at least one.
start (float, optional) – First azimuth in radians.

Returns:

npt.NDArray[np.float64] – start + 2 pi k / count for k = 0 .. count - 1, wrapped into [0, 2pi).

Raises:

ValueError – If count is not a positive integer or start is not finite.

Return type:

npt.NDArray[np.float64]

weight_kernel(azimuths, weights, orders)[source]

Return the quadrature-weight DFT kernel of an azimuth grid.

The kernel is \(W(h)=\sum_\ell w_\ell e^{jh\psi_\ell}\), the aliasing kernel of the grid.

Parameters:

azimuths (npt.ArrayLike) – Azimuths in radians.
weights (npt.ArrayLike) – One weight per azimuth.
orders (Sequence[int] or npt.ArrayLike) – Harmonic orders \(h\) at which to evaluate the kernel.

Returns:

npt.NDArray[np.complex128] – \(W(h)\) for each requested order. \(W(0)=\sum_\ell w_\ell\). On a uniform \(N\)-grid starting at \(\psi_0\) with equal weights, \(W(h)=e^{jh\psi_0}\) when \(N\mid h\) and zero otherwise.

Raises:

ValueError – If the weights do not match the azimuths or are non-finite.

Return type:

npt.NDArray[np.complex128]

zero_azimuth_column(matrices, azimuth)[source]

Zero the rotor-azimuth column (naive neutralisation, kept for comparison).

Parameters:

matrices (npt.ArrayLike) – One state matrix (n, n) or a stack (n_azimuth, n, n).
azimuth (AzimuthStates or int) – The rotor-azimuth position state.

Returns:

npt.NDArray[np.float64] – A copy with the azimuth column set to zero.

Raises:

ValueError – If the matrices are not square or the index is out of range.

Return type:

npt.NDArray[np.float64]

Notes

This is pin_azimuth() with \(\boldsymbol\xi=\mathbf e_{\mathrm{az}}\). It restores an exact zero eigenvalue and the perturbative regime of the sampling error, but \(\mathbf e_{\mathrm{az}}\) is not an eigenvector of the mean, so it changes the reference spectrum: the mean of the azimuth column carries the rotation of the steady cyclic blade deflection, which is physical. On archived floating-turbine linearizations it moved platform damping by up to 7 % of its value. Prefer pin_azimuth() with azimuth_tangent() of a dense grid.

The averaged (Coleman/MBC) analysis of a rotating turbine carries three errors that are usually only guessed at. Each is predicted here from the averaged model and the harmonic content of the samples, without a periodic (Floquet) solution:

Sampling. The error of a coarse or hypothetical azimuth grid. Its matrix error is exactly a quadrature-weight error times the harmonic content (vane.modal.averaging.grid_error_matrix()), and its effect on each branch follows from eigenvalue perturbation of the averaged eigensolution: first or second order, or, when the rotor-azimuth state is present, a structured predictor that keeps the azimuth column as an exact rank-one term and the near-Jordan azimuth/rotor-speed modes exactly. The structured predictor also yields a predicted modal assurance against the reference branch, the hybridisation flag.
Quadrature. The difference between the arithmetic sample mean (what the MBC transform applies) and the interval-weighted mean on the delivered grid.
Periodicity. The second-order sideband estimate of the Floquet exponent minus the averaged eigenvalue (vane.modal.averaging.sideband_correction()).

All terms are reported in the same units: the relative change of the damped frequency \(|\operatorname{Im}\lambda|\) and of the damping ratio \(\zeta=-\operatorname{Re}\lambda/|\lambda|\), in percent of the reference value. estimate_averaging_error() assembles them per branch, together with the azimuth consistency test. azimuth_count_table() designs the azimuth count from the \(\operatorname{lcm}(N, B)\) aliasing rule and the fitted harmonics, and commensurate_time_step() suggests a time step that puts every target azimuth on a whole number of steps.

class AliasTail(model, own_decay, tower_decay, own_level, peak_level, anchor_order, peak_order)[source]

Bases: object

Model of one branch’s harmonic sensitivity above the resolved orders.

Parameters:

model (str) – "own decay" (the branch’s own sensitivity peaks inside the resolved multiples of \(B\) and its fitted trend at least halves after), "tower law" (it does not, and the tower-passage decay of the azimuth column is used), "no content" (the sensitivity is rounding, the tail is zero) or "unresolved" (no tail can be justified from the samples).
own_decay (float) – Fitted decay per order of the branch’s own sensitivity (nan if unused).
tower_decay (float) – Tower-passage decay per order (nan if unused).
own_level (float) – Level of the smallest own-decay envelope through every fitted point, at anchor_order (1/s).
peak_level (float) – Largest observed sensitivity \(\max_h s_j(h)\) (1/s), the anchor of the tower-law envelope.
anchor_order (int) – The highest resolved multiple of \(B\).
peak_order (int) – The resolved order of the largest observed sensitivity.

model: str

own_decay: float

tower_decay: float

own_level: float

peak_level: float

anchor_order: int

peak_order: int

envelope(order)[source]

Return the tail estimate of \(s_j(h)\) at an order above the anchor.

Parameters:: order (int) – Harmonic order \(h\).
Returns:: float – The envelope of the tail model, nan when unresolved.
Return type:: float

class AveragingErrorEstimate(branches, azimuth, grid, reference_mean, rotor_speed, method, damping_tolerance_pct, frequency_tolerance_pct, max_condition=1000.0, sampling_status=None, sampling_first_alias=None, reference_resolved_order=None)[source]

Bases: object

Per-branch error estimates of an azimuth-averaged model.

Parameters:

branches (dict[str, BranchErrorEstimate]) – The assessed branches by label.
azimuth (AzimuthConsistency or None) – The azimuth consistency test, when the rotor-azimuth state was given.
grid (GridReport) – Quadrature properties of the delivered grid.
reference_mean (npt.NDArray[np.float64]) – The interval-weighted reference mean.
rotor_speed (float) – Rotor speed (rad/s).
method (str) – Branch predictor used for the sampling and quadrature terms.
damping_tolerance_pct (float) – Damping-ratio tolerance, percent of the reference value.
frequency_tolerance_pct (float) – Frequency tolerance, percent of the reference value.
max_condition (float, optional) – Eigenvalue condition number above which a branch is ill-conditioned.
sampling_status (str or None, optional) – "measured" (a sub-grid of the delivered samples), "resolved" (a predicted grid whose first alias order \(\operatorname{lcm}(N,B)\) lies within the resolved orders of the reference), "unresolved: needs denser reference ..." otherwise, None without a grid.
sampling_first_alias (int or None, optional) – \(\operatorname{lcm}(N,B)\) of a predicted grid of \(N\) azimuths.
reference_resolved_order (int or None, optional) – The highest harmonic order the reference samples resolve.

branches: dict[str, BranchErrorEstimate]

azimuth: AzimuthConsistency | None

grid: GridReport

reference_mean: npt.NDArray[np.float64]

rotor_speed: float

method: str

damping_tolerance_pct: float

frequency_tolerance_pct: float

max_condition: float = 1000.0

sampling_status: str | None = None

sampling_first_alias: int | None = None

reference_resolved_order: int | None = None

property azimuth_assessment: str | None

Return the graded azimuth assessment, None without the azimuth state.

Returns:: str or None – "consistent", "inconsistent-but-harmless" or "inconsistent-and-risky".

property within_tolerance: bool

Return whether every branch is within tolerance and the azimuth is not risky.

A harmless azimuth inconsistency (see azimuth_consistency()) does not void the branch budget; a risky one does.

class AzimuthCountRow(count, first_alias_order, multiple_of_blades, resolved_damping_error_pct, resolved_frequency_error_pct, unresolved_damping_bound_pct, total_damping_bound_pct, min_tracking_mac, hybridised, within_tolerance, resolved_damping_by_branch, unresolved_damping_by_branch, alias_resolved=True, resolved_within_tolerance=False)[source]

Bases: object

Predicted averaging error of one uniform azimuth count.

Parameters:

count (int) – Number of uniform azimuths \(N\).
first_alias_order (int) – \(\operatorname{lcm}(N, B)\).
multiple_of_blades (bool) – \(B \mid N\).
resolved_damping_error_pct (float) – Worst damping-ratio error over branches and start azimuths from the resolved harmonics (exact eigenvalues of the model’s uniform mean).
resolved_frequency_error_pct (float) – The same for the damped frequency.
unresolved_damping_bound_pct (float) – Worst first-order, worst-phase estimate of the aliases above the model’s highest order, from the documented tail model (nan when a branch’s tail is unresolved or extrapolation is off). It is a model-based estimate, not a bound.
total_damping_bound_pct (float) – Worst over branches of resolved plus tail estimate (nan when any tail is unresolved).
min_tracking_mac (float) – Lowest MAC with which a branch was tracked.
hybridised (bool) – Some branch was tracked with a MAC below the hybridisation threshold.
within_tolerance (bool) – total_damping_bound_pct is finite and within the tolerance: the extrapolated decision.
resolved_damping_by_branch (dict[str, float]) – Worst resolved damping-ratio error per branch.
unresolved_damping_by_branch (dict[str, float]) – Tail estimate per branch (nan when unresolved).
alias_resolved (bool, optional) – \(\operatorname{lcm}(N,B)\) lies within the orders the model resolves, so the resolved error contains the first alias of the count.
resolved_within_tolerance (bool, optional) – alias_resolved, not hybridised and the resolved error within the tolerance: the decision supported by the samples.

count: int

first_alias_order: int

multiple_of_blades: bool

resolved_damping_error_pct: float

resolved_frequency_error_pct: float

unresolved_damping_bound_pct: float

total_damping_bound_pct: float

min_tracking_mac: float

hybridised: bool

within_tolerance: bool

resolved_damping_by_branch: dict[str, float]

unresolved_damping_by_branch: dict[str, float]

alias_resolved: bool = True

resolved_within_tolerance: bool = False

class AzimuthCountTable(rows, recommended, blades, damping_tolerance_pct, extrapolated, recommended_resolved=None, recommended_extrapolated=None, extrapolation_status='not requested', tails=<factory>, resolved_order=0)[source]

Bases: object

Azimuth-count design table and its two recommendations.

Parameters:

rows (tuple[AzimuthCountRow, ...]) – One row per evaluated count, ascending.
recommended (int or None) – The recommendation supported by the samples, equal to recommended_resolved.
blades (int) – Blade count used for the lcm rule.
damping_tolerance_pct (float) – The damping-ratio tolerance, percent.
extrapolated (bool) – Whether a tail estimate was formed for at least one branch.
recommended_resolved (int or None, optional) – The smallest count whose first alias the model resolves and whose resolved error meets the tolerance. The resolved error is exact for the content the samples resolve, so this is the recommended count.
recommended_extrapolated (int or None, optional) – The smallest count whose resolved error plus tail estimate meets the tolerance. A model-based estimate, not a bound; None when a tail is unresolved.
extrapolation_status (str, optional) – "extrapolated", "not requested" or "unresolved: needs denser linearization ..." naming the branches whose tail cannot be modelled.
tails (dict[str, AliasTail], optional) – The tail model of each branch.
resolved_order (int, optional) – The highest harmonic order the model resolves.

rows: tuple[AzimuthCountRow, ...]

recommended: int | None

blades: int

damping_tolerance_pct: float

extrapolated: bool

recommended_resolved: int | None = None

recommended_extrapolated: int | None = None

extrapolation_status: str = 'not requested'

tails: dict[str, AliasTail]

resolved_order: int = 0

row(count)[source]

Return the row of one azimuth count.

Parameters:: count (int) – An evaluated azimuth count.
Returns:: AzimuthCountRow – Its row.
Raises:: KeyError – If count was not evaluated.
Return type:: AzimuthCountRow

class BranchErrorEstimate(label, index, eigenvalue, frequency_hz, damping_ratio, sampling, sampling_dominant_order, quadrature, periodicity, hybridised, within_tolerance, condition=nan, well_conditioned=True, sampling_exact=None, mixed=False, sampling_resolved=True)[source]

Bases: object

Error budget of one branch of the averaged model.

Parameters:

label (str) – Branch label.
index (int) – Index of the branch in the eigenbasis of the reference mean.
eigenvalue (complex) – Reference eigenvalue (1/s).
frequency_hz (float) – Reference damped frequency \(|\operatorname{Im}\lambda|/2\pi\).
damping_ratio (float) – Reference damping ratio.
sampling (ErrorEstimate or None) – Predicted error of the requested azimuth grid, None if no grid was given.
sampling_dominant_order (int or None) – Harmonic order contributing most to the first-order sampling error.
quadrature (ErrorEstimate) – Arithmetic mean versus the interval-weighted mean on the delivered grid.
periodicity (ErrorEstimate) – Second-order sideband (Floquet) estimate.
hybridised (bool) – The sampling term (exact when available) or the quadrature term has hybridised.
within_tolerance (bool) – The branch is well conditioned, its sampling term is resolved, every term is within the tolerances and none has hybridised or mixed.
condition (float) – Eigenvalue condition number \(\kappa_j=1/|\hat{\mathbf u}_j^H \hat{\mathbf v}_j|\) of the unit-norm left and right eigenvectors.
well_conditioned (bool) – \(\kappa_j\) does not exceed max_condition. Above it the perturbative terms (sampling prediction, quadrature, periodicity) cannot be trusted, and the branch is reported as ill-conditioned.
sampling_exact (ErrorEstimate or None) – The sampling error from the exact trial eigenproblem of the grid mean (the delivered samples for a measured sub-grid, the harmonic model otherwise), None when not computed.
mixed (bool) – The general mode-mixing check flagged the sampling term (exact when available) or the quadrature term.
sampling_resolved (bool) – The sampling term is a measurement (a sub-grid of the delivered samples) or a prediction whose first alias order the reference resolves. False means the term is only the resolved part of the error and the branch cannot be accepted for that grid (see AveragingErrorEstimate.sampling_status).

label: str

index: int

eigenvalue: complex

frequency_hz: float

damping_ratio: float

sampling: ErrorEstimate | None

sampling_dominant_order: int | None

quadrature: ErrorEstimate

periodicity: ErrorEstimate

hybridised: bool

within_tolerance: bool

condition: float = nan

well_conditioned: bool = True

sampling_exact: ErrorEstimate | None = None

mixed: bool = False

sampling_resolved: bool = True

property sampling_term: ErrorEstimate | None

exact when available.

Returns:: ErrorEstimate or None – sampling_exact if computed, else sampling.
Type:: Return the sampling term used for the assessment

class CommensurateStep(time_step, steps_per_azimuth, requested_time_step, relative_change, azimuth_spacing_deg, azimuth_per_step_deg)[source]

Bases: object

A time step that places every target azimuth on a whole number of steps.

Parameters:

time_step (float) – Suggested time step (s), never larger than the requested one.
steps_per_azimuth (int) – Whole number of steps between consecutive target azimuths.
requested_time_step (float) – The requested time step (s).
relative_change (float) – (requested - suggested) / requested.
azimuth_spacing_deg (float) – Target azimuth spacing, 360 / count degrees.
azimuth_per_step_deg (float) – Rotor rotation per suggested step, degrees.

time_step: float

steps_per_azimuth: int

requested_time_step: float

relative_change: float

azimuth_spacing_deg: float

azimuth_per_step_deg: float

class ErrorEstimate(shift, frequency_error_pct, damping_error_pct, mac, hybridised, method, mixing_mac=nan, mixed=False, shift_bound=nan)[source]

Bases: object

One predicted error term of a branch.

Parameters:

shift (complex) – Predicted eigenvalue change (1/s) relative to the reference branch.
frequency_error_pct (float) – Relative change of the damped frequency, percent (nan for a real reference eigenvalue).
damping_error_pct (float) – Relative change of the damping ratio, percent (nan for an undamped reference).
mac (float) – Predicted modal assurance of the perturbed eigenvector with the reference one (nan when the term predicts no eigenvector).
hybridised (bool) – mac is below the hybridisation threshold.
method (str) – "first", "second", "structured", "exact" or "sideband".
mixing_mac (float, optional) – Modal assurance of the general mode-mixing check: the reference eigenvector against its counterpart in the perturbed model, from the exact trial eigenproblem or from an exact solve over the modes strongly coupled to the branch, independent of the azimuth subspace (nan when not evaluated).
mixed (bool, optional) – mixing_mac is below the hybridisation threshold: the branch has mixed with another mode, whatever that mode is.
shift_bound (float, optional) – First-order conditioning bound \(\kappa_j\|\mathbf E\|_2\) on \(|\delta\lambda|\) (1/s), nan when not evaluated.

shift: complex

frequency_error_pct: float

damping_error_pct: float

mac: float

hybridised: bool

method: str

mixing_mac: float = nan

mixed: bool = False

shift_bound: float = nan

within(damping_tolerance_pct, frequency_tolerance_pct)[source]

Return whether both errors are within the tolerances and nothing mixed.

Parameters:

damping_tolerance_pct (float) – Damping-ratio tolerance, percent of the reference value.
frequency_tolerance_pct (float) – Frequency tolerance, percent of the reference value.

Returns:

bool – True when neither error exceeds its tolerance (an undefined, NaN error is not checked; an infinite one exceeds it) and the branch has neither hybridised nor mixed.

Return type:

bool

class GridReport(n_azimuths, max_gap_deviation_pct, kernel_orders, kernel_magnitude)[source]

Bases: object

Quadrature properties of the delivered azimuth grid.

Parameters:

n_azimuths (int) – Number of delivered azimuths.
max_gap_deviation_pct (float) – Largest deviation of a gap from the uniform spacing, percent.
kernel_orders (npt.NDArray[np.int]) – Orders 1 .. n_azimuths - 1.
kernel_magnitude (npt.NDArray[np.float64]) – \(|W_{\mathrm{ref}}(h)|\) of the interval weights at those orders: the fraction of each harmonic that leaks into the reference mean (zero to rounding on a uniform grid).

n_azimuths: int

max_gap_deviation_pct: float

kernel_orders: npt.NDArray[np.int_]

kernel_magnitude: npt.NDArray[np.float64]

alias_free_azimuth_count(blades, highest_order)[source]

Return the smallest uniform azimuth count free of aliases up to an order.

Parameters:

blades (int) – Blade count \(B\) (1 when the content is at every order).
highest_order (int) – Highest harmonic order with significant content.

Returns:

int – The smallest \(N\) with \(\operatorname{lcm}(N, B)\) greater than highest_order.

Raises:

ValueError – If blades or highest_order is not a positive integer.

Return type:

int

azimuth_count_table(model, branches=None, *, blades=3, counts=range(5, 37), starts=24, damping_tolerance_pct=1.0, extrapolate=True, max_alias_order=None, mac_threshold=0.9, tail_decay=None)[source]

Predict the averaging error of uniform azimuth counts and recommend one.

Parameters:

model (HarmonicModel) – Harmonic model of a dense set of samples (the interpolating trigonometric fit of fit_harmonics()). Branch errors are measured against its zeroth harmonic.
branches (Mapping[str, int | complex] or None, optional) – Branches to assess (as for estimate_averaging_error(), resolved against the eigenbasis of model.mean). Default every oscillatory mode.
blades (int, optional) – Blade count \(B\) for the \(\operatorname{lcm}(N, B)\) rule. Default 3.
counts (Iterable[int], optional) – Uniform azimuth counts to evaluate. Default 5 to 36.
starts (int, optional) – Start azimuths per count, spread over one grid spacing; the worst is kept.
damping_tolerance_pct (float, optional) – Damping-ratio tolerance, percent of the reference value.
extrapolate (bool, optional) – Form the tail estimate of the aliases above the model’s highest order.
max_alias_order (int or None, optional) – Highest alias order summed in the tail estimate; default None sums the geometric envelope to convergence, so the estimate does not depend on it.
mac_threshold (float, optional) – Tracking MAC below which a count is flagged hybridised.
tail_decay (float or TowerPassageFit or None, optional) – Tower-passage decay per order for branches whose own sensitivity does not decay within the resolved orders, either a number in \((0,1)\) or the fit of tower_passage_decay() to the delivered samples (it is ignored when its \(R^2\) in log is below 0.5). None leaves such branches unresolved.

Returns:

AzimuthCountTable – One row per count, the resolved and the extrapolated recommendation, the tail model of every branch and the extrapolation status.

Raises:

ValueError – If an argument is invalid or the model is not of square matrices.

Return type:

AzimuthCountTable

Notes

The resolved error is exact for the content the samples resolve: the exact eigenvalues of the uniform \(N\)-mean of the fitted model, worst over start azimuths. It contains the first alias of \(N\) only when \(\operatorname{lcm}(N,B)\) lies within the resolved orders (alias_resolved); only such counts are accepted, and recommended_resolved is the smallest of them meeting the tolerance. A 36-azimuth reference therefore confirms 5, 6, 9, 12 and 15 but not 7, 8, 10 or 13, whose first aliases (21 to 39) it cannot observe: for those the resolved error is only a lower estimate, and a denser reference is needed to confirm them.

The tail estimate is first order and worst phase, \(\sum_{m}\hat s_j(m\,\operatorname{lcm}(N,B))/\sigma_j\) over the aliases above the model’s highest order, with an envelope \(\hat s_j\) of the sensitivity \(s_j(h)=|\mathbf u_j^H\mathbf A_h\mathbf v_j|+|\mathbf u_j^H\mathbf A_{-h} \mathbf v_j|\):

own decay: when \(s_j\) peaks inside the resolved multiples of \(B\) and its log-linear fit from \(2B\) at least halves over the fitted orders, the smallest geometric envelope of that decay through every fitted point;
tower law: otherwise, \(\max_h s_j(h)\,(h/H)\,\rho^{h-H}\) from the highest resolved multiple \(H\), with the tower-passage decay \(\rho\) of the azimuth column (tail_decay), the law of the frozen-azimuth derivative of a localised inflow deficit;
neither: the branch is "unresolved", its tail and every total are nan, and the table reports "unresolved: needs denser linearization" instead of a recommendation.

Both envelopes are summable, so the estimate is independent of max_alias_order. It is a model-based extrapolation of orders the samples cannot observe, not a bound: on new OpenFAST linearizations of two floating turbines this estimate from 36 azimuths was exceeded at 13 azimuths (and, on the delivered column, at 18) and was up to 30 times conservative elsewhere. recommended_extrapolated is therefore an estimate, and recommended is the resolved count. With the delivered azimuth column the first-order tail is not valid (the near-Jordan azimuth/speed pair); evaluate the table on a pinned or neutralised model.

commensurate_time_step(rotor_speed, count, requested_time_step)[source]

Suggest a time step close to a requested one that is commensurate with the grid.

Parameters:

rotor_speed (float) – Rotor speed \(\Omega\) in rad/s.
count (int) – Number of uniform target azimuths per revolution (e.g. NLinTimes).
requested_time_step (float) – The time step the analyst would use (s).

Returns:

CommensurateStep – \(\Delta t=T/(Nk)\) with \(T=2\pi/\Omega\) and \(k\) the smallest whole number of steps per azimuth interval for which \(\Delta t\le\) requested_time_step.

Raises:

ValueError – If an argument is not positive and finite.

Return type:

CommensurateStep

Notes

A linearization snapshot is taken at the first time step at or past its target azimuth, so on a time step that does not divide the azimuth interval the delivered grid is non-uniform by up to \(\Omega\Delta t\). With a commensurate step and the rotor at the trimmed speed every snapshot falls on its target and the interval and arithmetic means coincide.

estimate_averaging_error(azimuths, matrices, rotor_speed, *, branches=None, azimuth=None, grid=None, method='auto', damping_tolerance_pct=1.0, frequency_tolerance_pct=0.1, periodicity_order=None, consistency_tolerance=0.0001, mac_threshold=0.9, subspace_share=0.05, exact=True, max_condition=1000.0, mixing_coupling=0.005, blades=3)[source]

Estimate the error of each branch of an azimuth-averaged model from the samples.

Parameters:

azimuths (npt.ArrayLike) – Delivered azimuths in radians (e.g. np.deg2rad(result.azimuths_deg)).
matrices (npt.ArrayLike) – Fixed-frame state matrices, shape (n_azimuth, n, n) (e.g. result.per_azimuth_a of an MBC result kept with retain_per_azimuth=True).
rotor_speed (float) – Rotor speed \(\Omega\) in rad/s.
branches (Mapping[str, int | complex] or None, optional) – Branches to assess: label to mode index of the reference mean or to an approximate eigenvalue (matched to the nearest one, on the same side of the real axis). Default every oscillatory mode (mode_00, … by frequency).
azimuth (AzimuthStates or None, optional) – The rotor-azimuth states (locate_azimuth_state()). Enables the consistency test and the structured predictor.
grid (int or npt.ArrayLike or None, optional) – The azimuth grid whose sampling error is predicted: explicit azimuths (a sub-grid of the delivered ones is measured exactly; any other grid is predicted from the interpolating harmonic model) or a count N for a hypothetical uniform grid starting at the first delivered azimuth. For the worst phase over start azimuths use azimuth_count_table(). None skips the sampling term.
method ({"auto", "first", "second", "structured"}, optional) – Branch predictor for the sampling and quadrature terms. "auto" uses "structured" when azimuth is given and "second" otherwise.
damping_tolerance_pct (float, optional) – Tolerances (percent of the reference value) for within_tolerance. The damping tolerance, as a fraction, is also the scale tolerance of the azimuth consistency test.
frequency_tolerance_pct (float, optional) – Tolerances (percent of the reference value) for within_tolerance. The damping tolerance, as a fraction, is also the scale tolerance of the azimuth consistency test.
periodicity_order (int or None, optional) – Highest harmonic order of the sideband estimate; default (M - 1) // 2.
consistency_tolerance (float, optional) – Absolute tolerance on the azimuth residual exponent, 1/s, reported as azimuth.absolute_consistent; the assessment uses the scaled test.
mac_threshold (float, optional) – MAC below which a branch is flagged hybridised or mixed.
subspace_share (float, optional) – Azimuth/speed participation share retained exactly by the structured predictor.
exact (bool, optional) – Also solve the trial eigenproblem of the grid mean (one dense eigen-solution) for the exact sampling term and the trial form of the mode-mixing check. Default True.
max_condition (float, optional) – Eigenvalue condition number above which a branch is ill-conditioned. Default 1e3.
mixing_coupling (float, optional) – Coupling-to-detuning ratio of the predicted mode-mixing check (see predict_branch_shift()).
blades (int, optional) – Blade count \(B\) of the \(\operatorname{lcm}(N,B)\) aliasing rule that decides whether a predicted grid is resolved. Default 3; use 1 for an anisotropic rotor.

Returns:

AveragingErrorEstimate – The per-branch budget, the azimuth consistency test and the grid report.

Raises:

ValueError – If the inputs are inconsistent or a tolerance is not positive.

Return type:

AveragingErrorEstimate

Notes

The sampling term of the analyst’s own full grid cannot be measured from that grid; assess interleaved sub-grids (grid=azimuths[::2]) or extrapolate the harmonic model with azimuth_count_table(). The quadrature and periodicity terms are fully a priori.

A grid that is not a sub-grid of the delivered samples is predicted from the interpolating harmonic model, which holds the orders up to the Nyquist order of the reference and nothing above. An \(N\)-azimuth grid of a \(B\)-bladed rotor is first aliased at \(\operatorname{lcm}(N,B)\). When that order lies above the resolved orders of the reference, the predicted term is only the resolved part of the error: the branch is reported with sampling_resolved=False and is not accepted, and sampling_status asks for a denser reference. On OpenFAST linearizations of two floating turbines, predictions from a 36-azimuth reference were exact for 12 azimuths (first alias 12) but recovered only 7 to 133 % of the error of 8, 10, 13 and 18 azimuths (first aliases 24 to 39 and the order-18 sine), while the same estimate built from a 72-azimuth reference recovered them all.

The predicted terms are perturbative and assume a well-conditioned branch: the first-order sensitivity of \(\lambda_j\) to a matrix error is \(\kappa_j\) (the pseudospectral bound \(|\delta\lambda_j|\le\kappa_j\|\mathbf E\|_2\), reported as shift_bound). A branch with \(\kappa_j>\) max_condition is reported as ill-conditioned; with exact=True its sampling term is still exact, but its quadrature and periodicity terms are not trusted. On the IEA 22 MW semi-submersible at 8 m/s the platform sway branch (\(\kappa\approx1.2\times 10^3\)) is under-predicted six- to eight-fold by every predictor on some sub-grids, which this check flags and the exact term measures.

first_alias_order(count, blades)[source]

Return the lowest harmonic order that aliases into a uniform count-mean.

Parameters:

count (int) – Number of uniform azimuths \(N\).
blades (int) – Blade count \(B\) (use 1 for content at every order).

Returns:

int – \(\operatorname{lcm}(N, B)\). When the periodic content after MBC lies only at multiples of \(B\) (an isotropic rotor), the \(N\)-sample mean is aliased only by common multiples of \(N\) and \(B\), so an \(N\) that is not a multiple of \(B\) pushes the first alias from \(N\) to \(BN\).

Raises:

ValueError – If either argument is not a positive integer.

Return type:

int

predict_branch_shift(basis, error, branches, *, method='second', azimuth=None, subspace_share=0.05, mac_threshold=0.9, mixing_coupling=0.005)[source]

Predict the change of reference branches caused by a matrix error.

Parameters:

basis (EigenBasis) – Eigentriples of the reference mean \(\mathbf A_0\).
error (npt.ArrayLike) – Matrix error \(\mathbf E\) (the perturbed model is \(\mathbf A_0+\mathbf E\)).
branches (Sequence[int]) – Mode indices into basis.values.
method ({"first", "second", "structured"}, optional) – "first": \(P_{jj}\); "second" (default): adds \(\sum_{k\neq j}P_{jk}P_{kj}/(\lambda_j-\lambda_k)\), with \(P=\mathbf U^H\mathbf E\mathbf V\); "structured": the azimuth column of \(\mathbf E\) is kept as an exact rank-one term and the modes with azimuth or rotor-speed participation above subspace_share are coupled exactly; every other mode keeps its first-order shift. Required when the rotor-azimuth state is present with its delivered column, where the azimuth/speed pair is nearly defective and ordinary perturbation breaks down.
azimuth (AzimuthStates or int or None, optional) – The rotor-azimuth states; required for "structured".
subspace_share (float, optional) – Participation share above which a mode is retained exactly. Default 0.05.
mac_threshold (float, optional) – Predicted MAC below which a branch is flagged hybridised or mixed. Default 0.9.
mixing_coupling (float, optional) – Coupling-to-detuning ratio above which a mode joins the branch’s cluster in the general mode-mixing check. Default 0.005.

Returns:

list[ErrorEstimate] – One estimate per requested branch, in order. For the first- and second-order methods the MAC is that of the first-order eigenvector correction. Every estimate also carries the general mode-mixing MAC (mixing_mac, mixed) and the first-order conditioning bound shift_bound.

Raises:

ValueError – If the error matrix does not match the basis, an index is out of range, the method is unknown, mixing_coupling is not positive, or "structured" is requested without azimuth.

Return type:

list[ErrorEstimate]

Notes

The hybridisation flag of "structured" sees only mixing through the azimuth subspace. The mixing check is independent of it: two modes are linked when their coupling \(\sqrt{|P_{ik}P_{ki}|}\) exceeds mixing_coupling times their detuning, and every mode connected to the branch by a chain of links is coupled exactly, so two branches that alias into each other (for example two heavily damped flap modes on a three-azimuth grid) are caught as well. On a coarse grid of a non-normal model the cluster can approach the whole model, and the cost that of the trial eigenproblem. The conditioning bound uses the eigenvalue condition number \(\kappa_j=\|\mathbf u_j\|\|\mathbf v_j\|/|\mathbf u_j^H\mathbf v_j|\): \(|\delta\lambda_j|\le\kappa_j\|\mathbf E\|_2\) to first order (the pseudospectral radius). It is rigorous to first order but on multi-scale models it is far from tight; the branch-level condition number is what estimate_averaging_error() tests.

trial_branch_shift(basis, trial, branches, *, mac_threshold=0.9)[source]

Solve a trial eigenproblem and track the reference branches in it.

Parameters:

basis (EigenBasis) – Eigentriples of the reference mean \(\mathbf A_0\).
trial (npt.ArrayLike) – The trial (perturbed) state matrix \(\mathbf A_0+\mathbf E\), for example a coarse sub-grid mean.
branches (Sequence[int]) – Mode indices into basis.values.
mac_threshold (float, optional) – Tracking MAC below which a branch is flagged mixed (and hybridised). Default 0.9.

Returns:

list[ErrorEstimate] – One "exact" estimate per branch: the eigenvalue of the trial matrix whose eigenvector has the largest MAC with the reference eigenvector (on the same side of the real axis), with that MAC as both mac and mixing_mac.

Raises:

ValueError – If the trial matrix does not match the basis or an index is out of range.

Return type:

list[ErrorEstimate]

Notes

This is the trial-eigenproblem form of the mode-mixing check: the exact answer for the given matrix, at the cost of one dense eigen-solution, and the reference for the predicted terms.

Campbell diagram

Campbell diagram assembly and nP excitation / resonance flagging.

Assembly of Campbell-diagram data from tracked modes.

A Campbell diagram plots modal natural frequency (and damping) against an operating parameter — rotor speed or wind speed — with one curve per tracked mode. This module pairs the mode tracks from vane.modal.identify_modes() with the operating-parameter value of each operating point, producing a structure ready for plotting or resonance analysis.

Heavily damped (near-critical) modes, which vane.modal.identify_modes() tracks in a tier of their own, are carried separately in CampbellDiagram.heavily_damped_tracks: they are drawn distinctly (or left out) and never enter the resonance analysis, since a mode damped near critically cannot resonate.

class CampbellDiagram(parameter_values, parameter_name, tracks, n_operating_points, heavily_damped_tracks=<factory>)[source]

Bases: object

Campbell-diagram data: tracked modes against an operating parameter.

Parameters:

parameter_values (npt.NDArray[np.float64]) – Operating-parameter value (e.g. rotor speed in rev/min) at each operating point, indexed by operating-point number, shape (n_operating_points,).
parameter_name (str) – Name of the operating parameter (e.g. "rotor_speed_rpm").
tracks (list[ModeTrack]) – The tracked modes, ordered by first natural frequency.
n_operating_points (int) – Number of operating points.
heavily_damped_tracks (list[ModeTrack]) – Tracks of heavily damped (near-critical) modes, kept apart from tracks: plotted distinctly and left out of resonance detection. Empty when the identification had none or they were not included.

parameter_values: npt.NDArray[np.float64]

parameter_name: str

tracks: list[ModeTrack]

n_operating_points: int

heavily_damped_tracks: list[ModeTrack]

track_curve(track)[source]

Return the operating-parameter, frequency, and damping arrays of a track.

Parameters:: track (ModeTrack) – A track belonging to this diagram.
Returns:: tuple of npt.NDArray[np.float64] – (parameter_values, natural_frequencies_hz, damping_ratios) along the track, each of length equal to the track’s span.
Return type:: tuple[npt.NDArray[np.float64], npt.NDArray[np.float64], npt.NDArray[np.float64]]

build_campbell(result, parameter_values, *, parameter_name='rotor_speed_rpm', include_heavily_damped=True)[source]

Build a Campbell diagram from identified mode tracks.

Parameters:

result (IdentificationResult) – The cross-operating-point mode tracks.
parameter_values (Sequence[float]) – Operating-parameter value at each operating point, in operating-point order; its length must equal result.n_operating_points.
parameter_name (str, optional) – Name of the operating parameter (default "rotor_speed_rpm").
include_heavily_damped (bool, optional) – Carry the identification’s heavily damped tracks into the diagram’s heavily_damped_tracks (default True); False omits them.

Returns:

CampbellDiagram – The assembled diagram.

Raises:

ValueError – If parameter_values length does not match the number of operating points, or the values are not a finite, one-dimensional, strictly increasing sweep axis (the excitation/resonance analysis interpolates against this axis, so duplicate, non-monotone, or non-finite values would give wrong crossings or raw errors).

Return type:

CampbellDiagram

campbell_from_solutions(solutions, parameter_values, *, parameter_name='rotor_speed_rpm', frequency_weight=0.5, mac_threshold=0.5, heavily_damped_threshold=0.99, rotor_speeds_rpm=None)[source]

Identify mode tracks from solutions and build a Campbell diagram.

Parameters:

solutions (Sequence[ModalSolution]) – Modal solutions, one per operating point, in operating-point order.
parameter_values (Sequence[float]) – Operating-parameter value at each operating point.
parameter_name (str, optional) – Name of the operating parameter.
frequency_weight (float, optional) – Passed through to vane.modal.identify_modes().
mac_threshold (float, optional) – Passed through to vane.modal.identify_modes().
heavily_damped_threshold (float or None, optional) – Passed through to vane.modal.identify_modes(); None tracks every mode together.
rotor_speeds_rpm (Sequence[float] or None, optional) – Rotor speed (rev/min) at each operating point, so blade whirl modes are classified by their rotating-frame damping. Defaults to parameter_values when parameter_name is "rotor_speed_rpm".

Returns:

CampbellDiagram – The assembled diagram.

Return type:

CampbellDiagram

Per-rev excitation lines and resonance detection.

A rotor turning at Omega excites the structure at integer multiples of the rotational frequency: the nP lines, with frequency n * rpm / 60 Hz. A potential resonance occurs where a mode’s natural-frequency curve crosses an nP line. For a three-bladed rotor the dominant excitations are 1P (rotor imbalance) and the blade-passing 3P, 6P, and 9P lines.

class ResonanceCrossing(track_index, harmonic, rotor_speed_rpm, frequency_hz, damping_ratio, severity)[source]

Bases: object

A crossing of a mode curve with an nP excitation line.

Parameters:

track_index (int) – Index of the crossing mode track within the diagram.
harmonic (int) – The excitation harmonic n (the nP line).
rotor_speed_rpm (float) – Rotor speed at the crossing, interpolated between operating points.
frequency_hz (float) – Frequency at the crossing, in hertz.
damping_ratio (float) – Damping ratio of the resonating mode at the crossing, interpolated between operating points.
severity (ResonanceSeverity) – Damping-aware severity of the crossing.

track_index: int

harmonic: int

rotor_speed_rpm: float

frequency_hz: float

damping_ratio: float

severity: ResonanceSeverity

class ResonanceSeverity(*values)[source]

Bases: Enum

Damping-aware severity of a resonance crossing.

A crossing’s danger depends on how lightly damped the resonating mode is: a near-undamped mode at a crossing can build large response, while a well-damped one is benign.

HIGH = 'high'

MEDIUM = 'medium'

LOW = 'low'

excitation_frequencies(rotor_speed_rpm, harmonics)[source]

Return the nP excitation-line frequencies at each rotor speed.

Parameters:

rotor_speed_rpm (npt.NDArray[np.float64]) – Rotor speed in rev/min, shape (n_points,).
harmonics (Sequence[int]) – The harmonics n to evaluate.

Returns:

dict[int, npt.NDArray[np.float64]] – Mapping of each harmonic n to its nP frequency (Hz) at every rotor speed, n * rpm / 60.

Raises:

ValueError – If harmonics contains a non-positive, fractional, non-finite, or duplicate value.

Return type:

dict[int, npt.NDArray[np.float64]]

find_resonances(diagram, harmonics=(1, 3, 6, 9), *, operating_range=None)[source]

Find where mode curves cross the nP excitation lines.

A crossing is detected wherever natural_frequency - n * rpm / 60 changes sign (or is zero) between consecutive operating points along a track; the rotor speed, frequency, and damping ratio at the crossing are linearly interpolated, and each crossing is assigned a damping-aware ResonanceSeverity.

The rotor-speed samples need not be strictly increasing: each track’s curve is sorted by rotor speed and duplicate rotor speeds are collapsed internally before the crossings are found, so a non-monotone or tied sweep is handled gracefully rather than producing spurious or zero-width crossings.

Parameters:

diagram (CampbellDiagram) – A Campbell diagram whose operating parameter is rotor speed in rev/min.
harmonics (Sequence[int], optional) – Excitation harmonics to test (default 1P, 3P, 6P, 9P). Any positive-integer family may be supplied.
operating_range (tuple[float, float] or None, optional) – If given, only crossings whose rotor speed falls within this (min_rpm, max_rpm) operating window are returned.

Returns:

list[ResonanceCrossing] – The detected crossings, in track-then-harmonic order.

Raises:

ValueError – If the diagram’s operating parameter is not rotor speed in rev/min, harmonics contains a non-positive, fractional, non-finite, or duplicate value, or operating_range is given with min_rpm > max_rpm.

Return type:

list[ResonanceCrossing]

Driving OpenFAST

Driving OpenFAST — execute linearizations and collect the .lin output.

This subpackage produces linearization data: it runs the OpenFAST executable on an input deck and gathers the resulting .lin files, ready for the parsing and modal pipeline.

The vane.run subpackage produces linearization data: it configures a deck for each operating point, runs the OpenFAST executable, and collects the .lin output. run_operating_sweep() runs a complete sweep from an operating curve (see The OpenFAST linearization sweep); the lower-level driver, operating-point, trim and steady-state functions are public as well. Every public name of the modules below, including helpers such as curve_power_coefficient() and rotor_radius() and constants such as FLOATING_TRIM_PERIODS, can also be imported from vane.run directly (from vane.run import curve_power_coefficient).

Linearization sweep

Automated operating-point sweep from rotor-performance data or settle runs.

FLOATING_TRIM_PERIODS = 20: Periods of the slowest platform mode a floating linearization trim runs for.

class OperatingSweepResult(operating_points, cases, settle_structural_dofs=None, settle_failures=(), floating_plan=None, auto_configuration=None)[source]

Bases: object

Result of a fully automated settle/linearize operating sweep.

Parameters:

operating_points (list[OperatingPoint]) – The linearized operating points, in wind_speeds order. Settle-derived points carry their settle_convergence and, when the settle runs were seeded from an operating curve, their settle_curve_check. A settle point that was not linearized is absent here and listed in settle_failures.
cases (list[SweepCase]) – The linearization cases, one per operating point.
settle_structural_dofs (dict[str, bool] or None, optional) – For a settle sweep, the template ElastoDyn flags the settle runs ran with for every structural DOF the linearization sets (the settle copy keeps the deck’s flags; see run_operating_sweep()). None without settle runs.
settle_failures (tuple of SettleFailure, optional) – The settle points that did not reach a confirmed equilibrium, in wind_speeds order, with their diagnostics. Empty when every point settled.
floating_plan (FloatingSettlePlan or None, optional) – For a settle sweep, how the settle runs were set up automatically: the controller library used (or that none was loadable, so the rotor was prescribed from the operating curve), the settle damping and the platform probe it was sized from (see plan_floating_settle()). None without settle runs.
auto_configuration (AutoConfiguration or None, optional) – Every value the sweep inferred from the deck and curve (template root, OpenFAST executable, rated wind speed and torque, pitch trim gain, module settings), each with its source, and the warnings raised while inferring them. None with auto_configure=False.

operating_points: list[OperatingPoint]

cases: list[SweepCase]

settle_structural_dofs: dict[str, bool] | None = None

settle_failures: tuple[SettleFailure, ...] = ()

floating_plan: FloatingSettlePlan | None = None

auto_configuration: AutoConfiguration | None = None

class SettleFailure(wind_speed, reason, message, linearized=False, operating_point=None, convergence=None)[source]

Bases: object

A settle point of a sweep that did not reach a confirmed equilibrium.

A sweep never aborts because one wind does not settle: the point is recorded here with its diagnostics, the other winds carry on, and only the points that settled are linearized (unless require_settled=False; see run_operating_sweep()).

Parameters:

wind_speed (float) – The wind speed (m/s) of the point.
reason ({"not_settled", "failed", "error"}) – "not_settled": the settle ran to completion but its criterion was not met (or could not be assessed). "failed": the settle could not complete (SteadyStateError, e.g. OpenFAST failed or its output could not be read). "error": an unexpected exception, which run_operating_sweep() re-raises once the sweep is complete.
message (str) – A one-line description of what went wrong.
linearized (bool) – Whether the point was linearized anyway ("not_settled" with require_settled=False, at the settle’s last mean).
operating_point (OperatingPoint or None, optional) – The settle’s last mean operating point (with its settle_convergence) when the settle ran to completion; None otherwise.
convergence (SettleConvergence or None, optional) – The settle evidence: the last RMS, every attempt with its horizon and window, the criterion, and for a two-stage settle the confirmation. None when the settle failed before any run was judged.

wind_speed: float

reason: SettleFailureReason

message: str

linearized: bool = False

operating_point: OperatingPoint | None = None

convergence: SettleConvergence | None = None

to_dict()[source]

Return the failure as a strict-JSON dictionary (unmeasured RMS as null).

Returns:: dict[str, object] – wind_speed, reason, message, linearized, the settled rotor_speed_rpm/blade_pitch_deg/platform when measured, and the convergence evidence.
Return type:: dict[str, object]

SettleFailureReason

Why a settle point is listed in OperatingSweepResult.settle_failures.

alias of Literal[‘not_settled’, ‘failed’, ‘error’]

exception SweepSettleError(message, *, result)[source]

Bases: SteadyStateError

Raised at the end of a sweep whose settle stage did not fully succeed.

Raised only after every wind has been settled and every usable point linearized, so no completed work is lost: the full OperatingSweepResult is attached as result. Raised when strict_settle=True and any point did not settle, or whenever a settle worker hit an unexpected exception (the first is chained as __cause__).

Parameters:

message (str) – The error message.
result (OperatingSweepResult) – The completed sweep result, including its settle_failures.

Return type:

None

floating_trim_time(period, max_sim_time)[source]

Return the CalcSteady run time of a floating linearization case.

The trim must outlast the slow platform motion the settled initial conditions leave, so the run spans FLOATING_TRIM_PERIODS periods of the slowest platform mode, within [MIN_CALC_STEADY_TMAX, max_sim_time].

Parameters:

period (float) – Slowest platform natural period (s), from the standstill platform probe.
max_sim_time (float) – Upper bound (s): the retry ladder’s max_sim_time.

Returns:

float – The run time TMax (s).

Raises:

ValueError – If period or max_sim_time is not finite and positive.

Return type:

tuple[LinearizationSettings, AutoConfiguration]

Notes

On the IEA 15-MW semi-submersible (slowest standstill period 125.5 s), settled cases linearized at the rotor-scaled TrimTol (7.1e-3) trimmed at 6, 8 and 12 m/s within 2400 s (about 19 periods; rotor-speed spread 0.08–0.09 %), but only at 8 m/s within 1200 s and at none within 600 s. Loosening TrimTol to 0.021 instead let the 6 m/s trim stop with a 6.6 % rotor-speed spread.

run_operating_sweep(fst_path, output_dir, wind_speeds, *, curve_wind=None, curve_rotor_speed=None, curve_pitch=None, performance_csv=None, settle=False, settle_time=1200.0, discard_time=600.0, max_settle_time=None, controller_library=None, settle_initial_platform=None, settle_curve_tolerances=None, settle_criterion='auto', settle_platform_damping=None, settle_confirm_time=None, settle_equilibrium_tolerances=None, settle_auto_damping=True, controller_search_paths=(), settings=None, structural_dofs=None, trim_tuning=None, retry_policy=None, executable=None, template_root=None, template_copy='referenced', timeout=None, max_workers=None, reserve_cpus=1, require_settled=True, strict_settle=False, strict_cases=False, validate=True, auto_configure=True)[source]

Derive operating points and run an OpenFAST linearization sweep.

The function refuses to guess the rotor speed and blade pitch. It needs a rotor-performance source: an operating curve (curve_wind/curve_rotor_speed/ curve_pitch) or a rotor-performance CSV (performance_csv) – not both – and/or settle=True to run the fully coupled controller first and read the operating point from the settled time series. Without any source, or with both a curve and a CSV, the sweep fails before any OpenFAST process is launched.

Everything else is configured automatically by default (auto_configure): run_operating_sweep(fst_path, output_dir, wind_speeds, performance_csv=csv) is a complete call. The copy root, the OpenFAST executable, the module settings and the turbine constants (rated wind speed, rated generator torque, pitch trim gain) are read from the deck and the curve, each logged and recorded with its source; anything that still cannot be made linearizable fails before launch with the keyword and its remedy.

The combinations mean:

curve or CSV alone – the curve, interpolated at each wind speed, is the linearization point.
settle=True alone – each settle run starts from 0 rpm and 0 deg collective pitch (written to the settle copy’s ElastoDyn RotSpeed/BlPitch) and the deck’s platform position; the settled point is linearized.
settle=True with a curve or CSV – the curve is used only as the settle runs’ initial conditions (RotSpeed and BlPitch(1..3) at each wind speed), so the rotor does not have to spin up from rest and start-up transients are smaller. The controller still decides where the turbine settles and the settled point is linearized, never the curve value. After each settle the settled rotor speed and pitch are compared with the curve (settle_curve_tolerances); a deviation outside tolerance is logged as a warning and recorded on the point’s settle_curve_check (and in the run provenance). It means the controller and the curve disagree and is not an error. Every requested wind speed must lie inside the curve’s range.

The platform offset is never estimated from the curve (VANE computes no thrust); it starts at the deck’s values unless settle_initial_platform supplies it.

Parameters:

controller_library (str or pathlib.Path or None, optional) – Bladed-style controller library (e.g. a libdiscon.dll built for this host) for the settle=True runs. Each settle case’s ServoDyn DLL_FileName is rewritten to it in the case copy only; the template deck is never edited. None (the default) finds one automatically (see find_controller_library()): the deck’s own DLL_FileName when it loads on this host, else a host build of the same library next to it or in controller_search_paths, VANE_CONTROLLER_LIBRARIES or the configuration file. When none exists the sweep does not fail: each settle runs with the rotor prescribed at the operating curve’s speed and pitch (no controller; prescribed_rotor of solve_steady_state()) and the point is linearized by CalcSteady from the platform equilibrium it finds – which requires an operating curve or performance_csv. The decision is recorded in OperatingSweepResult.floating_plan. Only valid with settle=True (the linearization replaces the controller by the trim and never loads the library).
settle_initial_platform (PlatformPosition or Mapping or None, optional) – Initial platform position for the settle runs: one PlatformPosition for every wind speed, or a mapping from wind speed to position (winds absent from it keep the deck’s position). Only the DOFs given are written. It is an initial condition only: a rough estimate (e.g. the mean surge and pitch of an earlier run) shortens the platform’s drift to its offset without changing where it settles. None (the default) keeps the deck’s platform position. Only valid with settle=True; every mapping key must be a requested wind speed.
settle_curve_tolerances (TrimTolerances or None, optional) – Tolerances of the settled-versus-curve comparison (rotor speed relative, pitch absolute; see compare_settled_to_curve()). None uses the TrimTolerances defaults (1 %, 0.5 deg). Only valid with settle=True and a curve or CSV.
settle_criterion ({"auto", "velocity", "mean_drift"}, optional) – How each settle run is judged settled (see solve_steady_state()): "auto" (the default) starts with the velocity criterion and switches to the mean-drift criterion when the platform carries a sustained, non-decaying oscillation; "velocity" is platform-velocity RMS within tolerance; "mean_drift" is operating-point means that no longer drift between the halves of the analysis window. The criterion that judged each point is recorded in its settle_convergence and in the run provenance. Only valid with settle=True.
settle_platform_damping (SettlePlatformDamping or None, optional) – Settle accelerator for floating platforms. None (the default) sizes it automatically for a floating deck from a standstill platform probe (see plan_floating_settle(); settle_auto_damping=False opts out). Each settle then runs in two stages, first with this temporary linear damping added to HydroDyn’s AddBLin in the settle copy, then undamped from the stage-1 means to confirm the equilibrium is unchanged (see solve_steady_state() and SettlePlatformDamping). The damping is only ever written to the settle case; every linearization case is copied afresh from the template and keeps the deck’s own AddBLin. The template must run HydroDyn with an AddBLin matrix; this is checked before any case is copied. Only valid with settle=True.
settle_confirm_time (float or None, optional) – TMax (s) of the undamped confirmation run of a two-stage settle. None (the default) sizes it automatically so its analysis window holds eight periods of the slowest platform mode – the platform probe’s longest period when the probe ran, else the damped stage’s dominant period – never shorter than 1200 s (the length without any period) and never longer than max_settle_time when given, else 3600 s (see confirm_time of solve_steady_state()). A decaying confirmation whose means have not yet returned to the damped equilibrium is rerun once twice as long. Used only with a settle damping.
settle_equilibrium_tolerances (EquilibriumTolerances or None, optional) – Tolerances on a change of the settled means (damped versus undamped stage, and window halves for "mean_drift"). None uses the EquilibriumTolerances defaults. Only valid with settle=True.
settle_auto_damping (bool, optional) – For a floating deck without settle_platform_damping, size the settle damping at half of critical from a standstill platform probe (two short linearizations in output_dir; see probe_platform()). Default True; False settles undamped.
controller_search_paths (Sequence of str or pathlib.Path, optional) – Extra controller-library files or directories searched when controller_library is not given.
performance_csv (str or pathlib.Path or None, optional) – Path to a rotor-performance CSV (see operating_curve_from_csv() for the column spec). When given it is parsed into the operating curve; it is mutually exclusive with the curve_* arrays. With settle=True it seeds the settle runs (see above).
structural_dofs (dict[str, bool] or None, optional) – ElastoDyn structural-DOF flags to set in each case’s ED sub-file. None (the default) keeps the settings object’s own value, whose default disables YawDOF and DrTrDOF for a reliable trim (dropping the spurious free-yaw mode and the ~0.62 Hz drivetrain-torsion mode, the latter a deliberate trade-off for trim convergence). Pass a mapping to override — it is merged on top of the defaults, so {"DrTrDOF": True} re-enables the drivetrain-torsion mode while still disabling YawDOF. A flag listed here but absent from the ED deck is an error. These flags apply to the linearization cases only: the settle copies keep the template deck’s own ElastoDyn DOF flags, because a settle runs the deck’s real controller on the model it was tuned for (a controller’s filters assume the deck’s drivetrain; the yaw drive holds the nacelle through ServoDyn). The settled mean rotor speed, pitch and platform position – all that is carried to the linearization – do not depend on the drivetrain or yaw flexibility. A difference between the two sets is logged, and the settle flags are recorded in OperatingSweepResult.settle_structural_dofs.
retry_policy (LinearizationRetryPolicy or None, optional) – The convergence retry ladder for the linearization cases (see LinearizationRetryPolicy), e.g. a larger max_sim_time for a slowly settling floating platform. None (the default) uses the default policy.
trim_tuning (TrimTuningPolicy or None, optional) – When set, each operating point’s starting trim tolerance and damping are tuned for its wind-speed region before the convergence retry ladder runs (see tune_trim_settings()): at/above-rated points start from the looser-tolerance, higher-damping floors those harder trims need, so they tend to converge on the first attempt rather than after a reactive retry. None (the default) starts every point from settings unchanged. Tuning only raises the per-case trim_tol/twr_kdmp/bld_kdmp toward the floors, so the sweep’s provenance is unaffected.
settings (LinearizationSettings or None, optional) – The linearization settings. None (the default) configures the deck automatically (with auto_configure): the offshore() module set, adapted to the deck – a HydroDyn radiation model whose .ss file is missing keeps RdtnMod 2 when the file can be fitted from the WAMIT .1 data (it is then generated in each case copy, hydro_radiation_fit), a radiation or excitation model whose state-space file cannot be had falls back to RdtnMod/ExctnMod 0 with a recorded warning, a deck’s own linearizable unsteady-aerodynamics model (UA_Mod 4-6) is kept with UAEndRad 0.99 where it would reach the tip node under tip loss, and a module the deck does not use is left untouched. Settings passed explicitly are used as given, except that the turbine constants they leave unset are still inferred (see auto_configure).
executable (str or pathlib.Path or None, optional) – The OpenFAST executable. None (the default) chooses one whose release reads the deck’s input-format generation, from the VANE_OPENFAST_EXECUTABLES environment variable, the file named by VANE_OPENFAST_CONFIG (default ~/.vane/openfast_executables.txt) and PATH (see select_openfast_executable()); the sweep fails before any case is copied, naming the release the deck needs, when none can. An explicit executable is used as given, but is rejected up front when its version is known not to read the deck.
template_root (str or pathlib.Path or None, optional) – Directory the deck’s files are copied from per case. None (the default) uses the deck’s own directory, or – when the deck references files outside it (../5MW_Baseline/...) and auto_configure is on – the deepest directory that holds the deck and every file it references by a relative path (infer_template_root()). An explicit value always wins.
template_copy ({"referenced", "tree"}, optional) – "referenced" (the default) copies only the files the deck references into each case (settle cases included); "tree" copies the whole template_root. See LinearizationDriver.
require_settled (bool, optional) – What to do with a settle point that does not reach a confirmed equilibrium (its criterion not met, or not assessable). True (the default): do not linearize it. False: linearize it at the settle’s last mean. Either way the sweep carries on with the other winds – one unsettled point never aborts it – and the point is listed in OperatingSweepResult.settle_failures with its diagnostics (and, when linearized, its settle evidence is in the case provenance). A settle that cannot complete (OpenFAST fails, unreadable output) is likewise recorded and never linearized.
strict_settle (bool, optional) – When True, raise SweepSettleError once the sweep is complete if any settle point is in settle_failures; the full result is attached as its result. Default False (the failures are logged and returned). An unexpected exception in a settle worker is always re-raised this way, after the other winds have been settled and linearized.
strict_cases (bool, optional) – How a linearization case that raises an unexpected exception (a file-system error while its case is copied or configured, say) is reported. Such a case never aborts the sweep: it is recorded in OperatingSweepResult.cases as failed (converged=False, failure_mode == "case_error") and the other points run to completion (see vane.run.LinearizationDriver.run_sweep()). Default False: the failure is logged and the result returned. True: raise vane.run.SweepCaseError once the sweep is complete, with the full result attached as its result.
validate (bool, optional) – When True (the default) the template deck is checked under the effective settings (validate_deck()) and every rotating curve point’s trim configuration is checked before any case is copied, and each configured case again before its OpenFAST run.
auto_configure (bool, optional) – When True (the default) the sweep completes its configuration from the user’s own deck and curve, logging every value and recording it with its source in OperatingSweepResult.auto_configuration, in the driver’s run provenance and in output_dir/auto_configuration.json (auto_configure_sweep()): the template root and executable (above), the module settings when settings is None, and the turbine constants left unset – rated_wind_speed (where the curve’s rotor speed and power reach their rated plateau), rated_generator_torque (controller DISCON.IN VS_RtTq, else ServoDyn VS_RtTq with VSContrl = 1, else the curve’s cp at rated) and a trim_gain_pitch left at its class default (scaled as 2e-4 * (63 m / TipRad)**3). VANE computes no rotor performance in doing so. False restores the explicit behaviour: nothing is inferred, settings=None means offshore(), and executable=None means "openfast" on PATH.
fst_path (str | Path)
output_dir (str | Path)
wind_speeds (Sequence[float])
curve_wind (Sequence[float] | None)
curve_rotor_speed (Sequence[float] | None)
curve_pitch (Sequence[float] | None)
settle (bool)
settle_time (float)
discard_time (float)
max_settle_time (float | None)
timeout (float | None)
max_workers (int | None)
reserve_cpus (int)

Raises:

SweepSettleError – After the sweep completes, with strict_settle=True and a settle failure, or when a settle worker raised an unexpected exception.
SweepCaseError – After the sweep completes, with strict_cases=True and a linearization case that raised an unexpected exception.
ValueError – Before any launch, for a malformed request or a rotating sweep whose rated wind speed is neither given nor inferable.
vane.run.DeckValidationError – Before any launch, when validate is on and the template cannot be linearized under the effective settings; every problem is listed with the keyword and its remedy.
vane.io.FastInputError – Before any launch, when a rotating curve point’s trim cannot be configured (e.g. no rated generator torque for an above-rated point).
vane.run.OpenFastError – Before any launch, when no OpenFAST executable can read the deck.

Return type:

OperatingSweepResult

Infer a linearization sweep’s turbine constants from the user’s deck and curve.

run_operating_sweep() needs a few turbine constants that a deck does not state in one place: the rated wind speed that separates torque trim from pitch trim, the rated generator torque the trim holds above rated and derives its torque gain from, a pitch-trim gain suited to the rotor’s size, and a module configuration OpenFAST can linearize. This module reads them from the user’s own inputs – the operating curve they supplied and the deck’s ElastoDyn, ServoDyn, AeroDyn, HydroDyn and controller input files – so a sweep runs with no other arguments. VANE still computes no rotor performance: every value is a constant read from, or arithmetic on, the user’s data, and each one is logged and recorded with its source (InferredValue, collected in AutoConfiguration) so the run provenance says where it came from. A value the user sets explicitly is never replaced.

The rules (see infer_rated_wind_speed(), infer_rated_generator_torque() and scaled_trim_gain_pitch() for the evidence behind each):

rated wind speed – the first curve wind at which the rotor speed has reached its plateau and, when the curve has a cp column, the aerodynamic power cp * V**3 has reached its plateau too. Cross-checked against the controller’s rated speed and power (DISCON.IN) when present; a disagreement is logged.
rated generator torque – the DISCON.IN VS_RtTq (the file named by ServoDyn DLL_InFile) when the deck runs a controller library; else ServoDyn VS_RtTq when VSContrl = 1; else the curve’s aerodynamic torque at rated from its cp column, ElastoDyn GBRatio/GBoxEff and the deck’s air density.
pitch trim gain – 1e-3 * (63 m / R)**3 with R the ElastoDyn TipRad.
module configuration (only when no settings are passed) – the offshore() preset adapted to the deck: a missing .ss radiation file is fitted from the WAMIT .1 data in each case copy when the fit is accurate enough (hydro_radiation_fit), other missing state-space hydrodynamics files fall back to RdtnMod/ExctnMod 0, a deck’s own linearizable unsteady-aerodynamics model is kept (with UAEndRad 0.99 where the tip node would otherwise carry it), and modules the deck does not use are left untouched.

DEFAULT_TRIM_GAIN_PITCH = 0.0002: The class-default pitch trim gain (rad/(rad/s)); a value left here is scaled.

DEFAULT_TRIM_TOL = 0.001: The class-default trim tolerance; a value left here is scaled.

MAX_SCALED_TRIM_TOL = 0.01: Upper bound of the scaled trim tolerance. The MBC3 transform accepts a rotor-speed spread of 1 % across the azimuth sweep, which a looser trim can exceed.

REFERENCE_ROTOR_RADIUS = 63.0: Rotor radius (m) at which the default trim gain and tolerance apply (NREL 5-MW).

class AutoConfiguration(inferred=(), warnings=())[source]

Bases: object

Everything a sweep inferred or adjusted on its own, for the provenance.

Parameters:

inferred (tuple[InferredValue, ...]) – The inferred values, in the order they were decided.
warnings (tuple[str, ...]) – Disagreements and fallbacks the user should know about (also logged).

inferred: tuple[InferredValue, ...] = ()

warnings: tuple[str, ...] = ()

get(name)[source]

Return the last record named name, or None.

Parameters:: name (str) – The record name.
Returns:: InferredValue or None – The record, when one was made.
Return type:: InferredValue | None

extended(inferred=(), warnings=())[source]

Return a copy with more records and warnings appended.

Parameters:

inferred (Sequence[InferredValue], optional) – Records to append.
warnings (Sequence[str], optional) – Warnings to append.

Returns:

AutoConfiguration – The extended configuration.

Return type:

AutoConfiguration

to_dict()[source]

Return the configuration as a JSON-serializable dictionary.

Returns:: dict[str, object] – inferred (a list of records) and warnings.
Return type:: dict[str, object]

class ControllerConstants(path, rated_power=None, rated_torque=None, rated_generator_speed=None, generator_efficiency=None, blade_radius=None)[source]

Bases: object

Rated constants read from a DISCON.IN-style controller input file.

Parameters:

path (pathlib.Path) – The controller input file (ServoDyn DLL_InFile).
rated_power (float or None) – VS_RtPwr (W, electrical).
rated_torque (float or None) – VS_RtTq (N·m, generator/HSS side).
rated_generator_speed (float or None) – VS_RefSpd (else PC_RefSpd), rad/s on the HSS.
generator_efficiency (float or None) – VS_GenEff as a fraction (the file holds percent).
blade_radius (float or None) – WE_BladeRadius (m).

path: Path

rated_power: float | None = None

rated_torque: float | None = None

rated_generator_speed: float | None = None

generator_efficiency: float | None = None

blade_radius: float | None = None

class InferredValue(name, value, source, detail='')[source]

Bases: object

One value VANE inferred or adjusted, with where it came from.

Parameters:

name (str) – What was inferred: a LinearizationSettings field name (rated_wind_speed, hydro_radiation_mode, …) or template_root / executable.
value (float or int or str or None) – The value used.
source (str) – The file and keyword, or the rule, it was taken from.
detail (str, optional) – Further evidence (cross-checks, the numbers combined).

name: str

value: float | int | str | None

source: str

detail: str = ''

to_dict()[source]

Return the record as a JSON-serializable dictionary.

Returns:: dict[str, object] – name, value, source and detail.
Return type:: dict[str, object]

auto_configure_sweep(fst_path, settings, *, curve_wind=None, curve_rotor_speed=None, curve_cp=None)[source]

Return sweep settings completed from the deck and curve, with the record.

With settings=None the module configuration is chosen for the deck (the offshore() preset, adapted as described in the module docstring). In every case the turbine constants the settings leave unset are inferred: rated_wind_speed and rated_generator_torque when None, and trim_gain_pitch and trim_tol when they were left at their class defaults (2e-4 and 1e-3, which apply to a 63 m rotor; see is_size_scaled_default()). Values set explicitly are kept, even when they equal the defaults.

Parameters:

fst_path (str or pathlib.Path) – The primary .fst deck.
settings (LinearizationSettings or None) – The user’s settings, or None for a fully automatic configuration.
curve_wind (Sequence[float] or None, optional) – The operating curve (m/s, rpm), when one was supplied.
curve_rotor_speed (Sequence[float] or None, optional) – The operating curve (m/s, rpm), when one was supplied.
curve_cp (Sequence[float] or None, optional) – The curve’s power coefficients, when its CSV has a cp column.

Returns:

tuple[LinearizationSettings, AutoConfiguration] – The completed settings and every inferred value with its source.

Return type:

Notes

A constant that cannot be inferred is left unset; the sweep’s boundary checks then fail before launch with the keyword to supply.

curve_power_coefficient(csv_path, curve_wind)[source]

Return a performance CSV’s cp column aligned with curve_wind.

Parameters:

csv_path (str or pathlib.Path) – The rotor-performance CSV (as given to run_operating_sweep()).
curve_wind (Sequence[float]) – The curve’s wind speeds as operating_curve_from_csv() returned them (sorted ascending).

Returns:

list[float] or None – The power coefficient (a fraction) at each curve wind, or None when the file cannot be read, has no cp column, its rows do not match curve_wind, or any cp value is missing, non-numeric or negative.

Raises:

ValueError – If the cp column’s unit or scale is wrong or ambiguous, as for rotor_performance_from_csv(): the header accepts the same column names (cp, power_coefficient, RtAeroCp, RtFldCp, only one of them) and units (none, [-], [1] or [fraction] for a fraction; [%], [percent] or [pct] for a percentage, which is converted), a fraction above the Betz limit 16/27 is rejected as a percentage written without its unit, and a column declared in percent whose values are all at most 1 is rejected as fractions labelled as percent.

Return type:

list[float] | None

infer_rated_generator_torque(fst_path, *, curve_wind=None, curve_rotor_speed=None, curve_cp=None, controller=None)[source]

Return the rated generator torque (N·m, HSS side) from the deck or the curve.

Sources, in order:

the controller input file’s VS_RtTq (DISCON.IN, the file named by ServoDyn DLL_InFile) when the deck runs a controller library;
ServoDyn VS_RtTq when VSContrl = 1 (the simple variable-speed law actually uses it; under a library it is a placeholder);
the curve’s aerodynamic torque at rated, Q = cp * rho/2 * pi * R**2 * V**3 / Omega averaged over the rated region, moved to the generator side with ElastoDyn GBoxEff and GBRatio (Q * GBoxEff / GBRatio), when the curve has a cp column.

Parameters:

fst_path (str or pathlib.Path) – The primary .fst deck.
curve_wind (Sequence[float] or None, optional) – The operating curve and its power coefficients, for source 3.
curve_rotor_speed (Sequence[float] or None, optional) – The operating curve and its power coefficients, for source 3.
curve_cp (Sequence[float] or None, optional) – The operating curve and its power coefficients, for source 3.
controller (ControllerConstants or None, optional) – The deck’s controller constants, when already read (read_controller_constants() is called otherwise).

Returns:

InferredValue or None – The torque with its source, or None when no source has it.

Return type:

InferredValue | None

Notes

The torque trim gain is derived from this value as a tenth of it (Jonkman’s rule of thumb). On the low-speed shaft that loop’s proportional gain is 1000 * TrimGain * GBRatio = 100 * Q_rated, so its time constant J / (100 * Q_rated) (J the ElastoDyn rotor and drivetrain inertia) is 0.10 s for the NREL 5-MW, 0.14 s for the IEA 3.4-MW, 0.19 s for the IEA 10-MW, 0.18 s for the IEA 15-MW and 0.23 s for the IEA 22-MW: the rule scales with size by construction, since the rated torque grows with the rotor. Source 3 reproduces the published rated torques within 0.3 % (NREL 5-MW), 1.1 % (IEA 15-MW) and 3.9 % (IEA 22-MW).

infer_rated_wind_speed(curve_wind, curve_rotor_speed, curve_cp=None)[source]

Return the rated wind speed of an operating curve, and how it was found.

Rated is the first curve wind at which the rotor speed has reached its plateau (within 0.5 % of the curve’s maximum, held for at least two samples) and, when curve_cp is given, the aerodynamic power cp * V**3 has also reached its plateau: from that wind on, every curve sample is within 0.5 % of the curve’s final power (at least two samples). A power still rising through the last samples has no plateau.

Parameters:

curve_wind (Sequence[float]) – The operating curve (m/s, rpm).
curve_rotor_speed (Sequence[float]) – The operating curve (m/s, rpm).
curve_cp (Sequence[float] or None, optional) – The curve’s power coefficients, aligned with curve_wind.

Returns:

tuple[float, str] – The rated wind speed (m/s) and a description of the evidence.

Raises:

ValueError – If the curve has no rotor-speed plateau (e.g. it stops below rated), or its sequences differ in length.

Return type:

tuple[float, str]

Notes

The rated wind speed selects the CalcSteady trim: below it the generator torque is trimmed at the curve’s pitch, at and above it the pitch is trimmed against a constant rated torque. The boundary that matters is therefore where the generator torque reaches rated, i.e. where the rotor speed is at its rated value and the power has stopped rising. The point where the pitch starts to rise is not used: a peak-shaving schedule pitches before rated (the published NREL 5-MW curve from 11.1 m/s, while its rotor speed and power level off at 12.12 m/s), and a fine-pitch schedule pitches below rated too. On the published reference curves the rule gives 12.12 m/s (NREL 5-MW published curve), 9.81 m/s (IEA 3.4-MW curve; published 9.8), 10.76 m/s (IEA 10-MW curve, whose rotor speed levels off at 10.27 m/s while the power still rises to 10.76 m/s), 10.66 m/s (IEA 15-MW curve; published 10.66) and 11.13 m/s (IEA 22-MW curve; published 11.13). On a coarse curve without cp (an IEA 22-MW operating table on a 1 m/s grid) the first plateau sample (12 m/s) is returned, which errs to the safe side: a point between the true rated speed and it is torque-trimmed at the curve’s pitch, which converges like any below-rated point.

read_controller_constants(fst_path)[source]

Return the rated constants of the deck’s controller input file, if any.

The file is ServoDyn’s DLL_InFile (resolved relative to the ServoDyn file), read only when ServoDyn is enabled and runs a control channel through the Bladed-style library (PCMode, VSContrl, HSSBrMode or YCMode = 5). The value ! Keyword - description layout of DISCON.IN is parsed; VS_RtPwr, VS_RtTq, VS_RefSpd (or PC_RefSpd), VS_GenEff and WE_BladeRadius are read.

Parameters:: fst_path (str or pathlib.Path) – The primary .fst deck.
Returns:: ControllerConstants or None – The constants (each None when absent or not positive), or None when the deck has no readable controller input file or it holds none of them.
Return type:: ControllerConstants | None

rotor_radius(fst_path)[source]

Return the rotor radius (ElastoDyn TipRad, m) of a deck, if readable.

Parameters:: fst_path (str or pathlib.Path) – The primary .fst deck.
Returns:: float or None – TipRad, or None when the deck has no readable positive value.
Return type:: float | None

scaled_trim_gain_pitch(radius)[source]

Return the default CalcSteady pitch trim gain for a rotor of radius.

The rule is 2e-4 * (63 m / R)**3 rad/(rad/s).

Parameters:: radius (float) – Rotor radius R (m), ElastoDyn TipRad.
Returns:: float – The pitch trim gain (TrimGain for TrimCase = 3).
Raises:: ValueError – If radius is not finite and positive.
Return type:: float

Notes

ServoDyn’s pitch trim is a PI law on the rotor-speed error e (rad/s): each step adds TrimGain * e to an integrator and the pitch offset adds 1000 * TrimGain * e on top, so the proportional gain is 1000 * TrimGain and the integral gain TrimGain / DT. The aerodynamic torque a pitch change produces, dQ/dtheta, scales with rho * R**3 * V**2 at the similar rated wind speeds of utility turbines, so holding the trim’s torque correction per unit speed error (1000 * TrimGain * dQ/dtheta) at its NREL 5-MW value gives TrimGain proportional to R**-3. It is anchored at the class default 2e-4 for R = 63 m. The ElastoDyn rotor inertia about the low-speed shaft (blades, hub and generator) grows nearly as fast, as R**3.4 over the NREL 5-MW and IEA 3.4/10/15/22-MW turbines (4.4e7 to 7.1e8 kg·m²), so the rule also keeps TrimGain times that inertia within a factor of two of the NREL 5-MW value on all five.

Single-attempt CalcSteady trims give the evidence. The anchor was 1e-3 until the reference-turbine campaign showed that the r-test NREL 5-MW land deck (63 m, DT 6.25 ms) oscillates or motors above rated with it: at 16 m/s 1e-3 keeps oscillating while 6.3e-4, 5e-4 and 2e-4 converge, and at 13 m/s, just above rated, everything above 2e-4 motors. With the 2e-4 anchor every NREL 5-MW point, the IEA 3.4-MW (64.9 m) from 9 to 25 m/s and every IEA 15-MW (121.0 m) and 22-MW (141.0 m) point above rated trim on the first attempt. Before that, the 1e-3 anchor diverged on the IEA 10-, 15- and 22-MW, and its scaled 2.6e-4 converged the IEA 10-MW (99.2 m) at 12 m/s.

scaled_trim_tol(radius)[source]

Return the default CalcSteady trim tolerance for a rotor of radius.

The rule is 1e-3 * (R / 63 m)**3, kept within [1e-3, 1e-2].

Parameters:: radius (float) – Rotor radius R (m), ElastoDyn TipRad.
Returns:: float – The trim tolerance (TrimTol).
Raises:: ValueError – If radius is not finite and positive.
Return type:: float

Notes

TrimTol bounds the change of the trimmed outputs from one rotor revolution to the next. Without trim damping, the lightly damped tower and blade motion of a large, flexible turbine decays too slowly for a tight tolerance, while the rotor speed of a small, light rotor needs one: the MBC3 transform accepts a rotor-speed spread of at most 1 % across the azimuth sweep.

Single-attempt trims on the reference-turbine campaign bracket the rule. At 1e-3 the IEA 3.4-MW (64.9 m) and the NREL 5-MW (63 m) converge every point, but the IEA 15-MW (121.0 m) converges only 4 of 9 and the IEA 22-MW (141.0 m) 2 of 9. At 1e-2 the IEA 15-MW converges 8 of 9 and the IEA 22-MW 9 of 9, while the IEA 3.4-MW’s below-rated points stop with a rotor-speed spread of 1.02–2.57 % that the MBC3 check rejects. Against the points that converge at both tolerances, 1e-2 changes the frequencies below 3 Hz by at most 0.1 %, the damping ratios by at most 0.1 percentage point and the trimmed generator torque by at most 0.8 %. The rule gives 1e-3 to 1.1e-3 for the 63–65 m rotors, 3.9e-3 for the IEA 10-MW (99 m), 7.1e-3 for the IEA 15-MW and the 1e-2 bound for the IEA 22-MW. A trim that still does not converge is retried with a looser tolerance and a longer run.

Operating points for a linearization sweep.

A linearization is taken at a single operating point — a wind speed, a rotor speed, and a blade-pitch angle. A Campbell diagram or a load/QoI sweep needs a series of them across the operating envelope. This module defines OperatingPoint and builds a sweep either from an explicit list or by interpolating a turbine’s steady-state operating curve (the rotor speed and pitch a controller would hold at each wind speed), so a user need only choose the wind speeds to cover.

class OperatingPoint(wind_speed, rotor_speed_rpm, blade_pitch_deg, name='', platform=None, settle_convergence=None, settle_curve_check=None)[source]

Bases: object

A single steady operating point for a linearization.

Parameters:

wind_speed (float) – Hub-height wind speed in m/s. 0 denotes a no-wind (standstill or still-air) point.
rotor_speed_rpm (float) – Rotor speed in rev/min. 0 denotes a parked/standstill rotor.
blade_pitch_deg (float) – Collective blade-pitch angle in degrees.
name (str) – Optional label for the point (used to name a generated case directory).
platform (PlatformPosition or None) – Initial floating-platform position to set in ElastoDyn. None (the default) leaves the platform degrees of freedom at the deck’s values — appropriate for a bottom-fixed turbine or when the deck is already at equilibrium.
settle_convergence (SettleConvergence or None) – Audited platform-velocity convergence from solve_steady_state(), when the point came from a settle run. Hand-authored curve points leave it None.
settle_curve_check (SettleCurveCheck or None) – For a settle run seeded from an operating curve, the settled rotor speed and pitch compared with the curve at this wind speed (see compare_settled_to_curve()); None otherwise.

wind_speed: float

rotor_speed_rpm: float

blade_pitch_deg: float

name: str = ''

platform: PlatformPosition | None = None

settle_convergence: SettleConvergence | None = None

settle_curve_check: SettleCurveCheck | None = None

property is_rotating: bool: Return whether the rotor turns under wind (a periodic operating point).

class PlatformPosition(surge=None, sway=None, heave=None, roll=None, pitch=None, yaw=None)[source]

Bases: object

Rigid-body floating-platform position (ElastoDyn platform DOFs).

Up to six platform degrees of freedom used to start a floating linearization at its thrust-loaded equilibrium, so the steady-state trim does not have to drag the slow platform modes there from rest (which it cannot reliably do near peak thrust). Translations are in metres and rotations in degrees, matching ElastoDyn’s PtfmSurge/PtfmSway/PtfmHeave/PtfmRoll/PtfmPitch/PtfmYaw.

Each field defaults to None, meaning leave that DOF at the deck’s value; only the DOFs given are written. This keeps a partially-known position (e.g. only the surge and pitch a deck happens to output) from overwriting the deck’s other platform DOFs with fabricated zeros.

Parameters:

surge (float or None) – Platform translational displacements in metres, or None to leave unchanged.
sway (float or None) – Platform translational displacements in metres, or None to leave unchanged.
heave (float or None) – Platform translational displacements in metres, or None to leave unchanged.
roll (float or None) – Platform rotational displacements in degrees, or None to leave unchanged.
pitch (float or None) – Platform rotational displacements in degrees, or None to leave unchanged.
yaw (float or None) – Platform rotational displacements in degrees, or None to leave unchanged.

surge: float | None = None

sway: float | None = None

heave: float | None = None

roll: float | None = None

pitch: float | None = None

yaw: float | None = None

operating_curve_from_csv(path)[source]

Parse a rotor-performance CSV into a steady operating curve.

Reads a header-row CSV of the turbine’s steady operating schedule and returns the (curve_wind, curve_rotor_speed, curve_pitch) arrays run_operating_sweep() and operating_points_from_curve() consume, sorted by ascending wind speed.

The CSV must have a header row naming its columns. Three columns are required (canonical names, with tolerated variants — header matching ignores case, whitespace, and separators):

wind_speed (m/s) – also WindSpeed, wind, V [m/s], U;
rotor_speed_rpm (rpm) – also RotSpeed, Omega [rpm], rpm;
blade_pitch_deg (deg) – also BldPitch, pitch [deg], theta.

A unit written in square brackets or parentheses after a required column’s name is parsed (case- and whitespace-insensitive) and the column converted to the canonical unit; a column without a unit is taken to be in the canonical unit:

wind speed accepts m/s (also mps, m s^-1) and converts km/h (also kmh, kph) by 1/3.6;
rotor speed accepts rpm (also rev/min) and converts rad/s by 60/(2*pi);
blade pitch accepts deg (also degree, degrees) and converts rad by 180/pi.

Any other unit on a required column raises ValueError rather than being silently misread, as does a converting unit on a header whose name states the canonical unit (rotor_speed_rpm [rad/s]). Each conversion is logged at INFO. Units are read from the header only; a separate units row is not supported and fails as a non-numeric value. Any other columns (cp, ct, cq, gen_power, …) are ignored here, units included, so a standard rotor-performance export drops in unchanged; rotor_performance_from_csv() reads the cp and ct columns with their units.

Parameters:

path (str or pathlib.Path) – Path to the rotor-performance CSV file.

Returns:

tuple of three list[float] – (curve_wind, curve_rotor_speed, curve_pitch), sorted by ascending wind speed.

Raises:

FileNotFoundError – If path does not exist.
ValueError – If the file is unreadable or empty, a required column is missing or carries an unsupported (or name-contradicting) unit, a value is non-numeric, NaN, or infinite, a wind speed or rotor speed is negative (negative collective blade pitch is allowed), there are fewer than two data rows (at least two operating points are needed to interpolate), or the wind speeds are duplicated or not strictly increasing once sorted.

Return type:

tuple[list[float], list[float], list[float]]

operating_curve_from_performance(*, performance_table=None)[source]

Derive a steady operating curve from a tabulated rotor-performance schedule.

Returns the (curve_wind, curve_rotor_speed, curve_pitch) arrays that operating_points_from_curve() and run_operating_sweep() consume, from an explicit performance_table – the turbine’s tabulated steady operating schedule (wind speed, rotor speed, collective pitch), validated and returned sorted by ascending wind speed. The rotor-performance data is always supplied by the caller (e.g. read from a CSV with operating_curve_from_csv()); VANE does not compute it from blade geometry.

Parameters:

performance_table (tuple of three Sequence[float] or None, optional) – (wind_speed, rotor_speed_rpm, blade_pitch_deg) arrays of the turbine’s steady operating schedule, of equal length (>= 2).

Returns:

tuple of three list[float] – (curve_wind, curve_rotor_speed, curve_pitch), sorted by ascending wind speed, ready to pass to operating_points_from_curve().

Raises:

ValueError – If performance_table arrays differ in length, have fewer than two samples, contain a non-finite value, have a negative wind speed or rotor speed (negative collective blade pitch is allowed), or have a non-increasing wind-speed axis.
RuntimeError – If no performance_table is given, so there is no rotor-performance source to derive the curve from.

Return type:

tuple[list[float], list[float], list[float]]

operating_points_from_curve(wind_speeds, *, curve_wind, curve_rotor_speed, curve_pitch)[source]

Build operating points by interpolating a steady-state operating curve.

The turbine’s steady operating curve (rotor speed and collective pitch versus wind speed) is interpolated with a shape-preserving monotone cubic (PCHIP, which does not overshoot between samples) and evaluated at each requested wind speed.

Parameters:

wind_speeds (Sequence[float]) – Wind speeds (m/s) to produce operating points at.
curve_wind (Sequence[float]) – Strictly increasing wind-speed samples of the operating curve.
curve_rotor_speed (Sequence[float]) – Rotor speed (rpm) at each curve_wind sample.
curve_pitch (Sequence[float]) – Collective blade pitch (deg) at each curve_wind sample.

Returns:

list[OperatingPoint] – One operating point per requested wind speed, named "ws<speed>".

Raises:

ValueError – If the curve arrays differ in length or have fewer than two points, the curve wind speeds are not strictly increasing, any curve value is non-finite, or a requested wind speed is non-finite or falls outside the curve’s range (interpolation only — extrapolation is not performed).

Return type:

list[OperatingPoint]

End-to-end linearization driver: a turbine model and a sweep to .lin files.

The LinearizationDriver ties the pieces together. Given a template OpenFAST case and a list of operating points, it copies the case to a fresh directory per point, configures each copy for linearization at that point (vane.run.configure_linearization()), runs OpenFAST (vane.run.run_openfast()), and collects the resulting .lin files — which feed straight into the parsing and modal pipeline. This closes the loop from a turbine model to a Campbell diagram / load (QoI) sweep / mode shapes, all from VANE.

A case is copied per operating point so that shared sub-files (a common InflowWind or ElastoDyn deck) are never mutated across points. By default the case’s own directory is the copy root; pass template_root to a higher directory when the deck references files outside it (e.g. ../5MW_Baseline/...). Only the files the deck references are copied (vane.run.deck_files.copy_template_files()), at their paths relative to template_root, so a broad root such as a whole regression-test suite costs only the deck’s own inputs per case.

class CaseProvenance(name, wind_speed, rotor_speed_rpm, blade_pitch_deg, case_dir, returncode, succeeded, n_lin, attempts=1, converged=True, trim_tol=0.0, twr_kdmp=0.0, bld_kdmp=0.0, trim_gain_torque=0.0, trim_gain_pitch=0.0, settle_assessed=None, settle_converged=None, settle_translational_velocity_rms=None, settle_angular_velocity_rms=None, settle_time=None, settle_iterations=None, settle_attempts=None, settle_criterion=None, settle_confirmation=None, settle_curve_rotor_speed_rpm=None, settle_curve_pitch_deg=None, settle_curve_status=None, operating_point_residual=None, sim_time=None, failure_mode=None, attempt_history=(), fallback_overrides=None, radiation_fit=None)[source]

Bases: object

Per-operating-point record within a sweep’s provenance.

Parameters:

name (str) – The case-directory name for the operating point.
wind_speed (float) – Hub-height wind speed (m/s).
rotor_speed_rpm (float) – Rotor speed (rpm).
blade_pitch_deg (float) – Collective blade pitch (deg).
case_dir (str) – The case directory the run was written to.
returncode (int) – OpenFAST exit status (0 on success).
succeeded (bool) – Whether OpenFAST exited successfully.
n_lin (int) – Number of full-system .lin files produced.
attempts (int) – How many OpenFAST runs the retry ladder used for this point.
converged (bool) – Whether the final attempt converged to a trustworthy linearization.
trim_tol (float) – The as-run trim tolerance for this case (escalated above the campaign base when the case was retried).
twr_kdmp (float) – The as-run tower/blade trim damping for this case (escalated on retry).
bld_kdmp (float) – The as-run tower/blade trim damping for this case (escalated on retry).
trim_gain_torque (float) – The as-run torque/pitch trim gains for this case. trim_gain_torque is the effective torque gain (the escalated override on a retry, else rated_generator_torque / 10 when derived, else the explicit value). Recorded per case because the gain is a per-case escalation ignored by the campaign-wide settings record.
trim_gain_pitch (float) – The as-run torque/pitch trim gains for this case. trim_gain_torque is the effective torque gain (the escalated override on a retry, else rated_generator_torque / 10 when derived, else the explicit value). Recorded per case because the gain is a per-case escalation ignored by the campaign-wide settings record.
settle_* (optional) – Platform-velocity settle evidence carried by a point produced through vane.run.solve_steady_state(); None for hand-authored curve points.
settle_criterion (str or None) – The criterion that accepted (or rejected) the settle: "velocity" or "mean_drift" (see vane.run.solve_steady_state()).
settle_confirmation (SettleConfirmation or None) – For a two-stage settle with temporary platform damping, the damped stage’s evidence and the undamped confirmation’s outcome; None otherwise.
settle_curve_rotor_speed_rpm (optional) – For a settle seeded from an operating curve, the curve’s rotor speed (rpm) and pitch (deg) at this wind speed and the settled-versus-curve status ("pass", "flag" or "unavailable"; see vane.run.SettleCurveCheck); None otherwise.
settle_curve_pitch_deg (optional) – For a settle seeded from an operating curve, the curve’s rotor speed (rpm) and pitch (deg) at this wind speed and the settled-versus-curve status ("pass", "flag" or "unavailable"; see vane.run.SettleCurveCheck); None otherwise.
settle_curve_status (optional) – For a settle seeded from an operating curve, the curve’s rotor speed (rpm) and pitch (deg) at this wind speed and the settled-versus-curve status ("pass", "flag" or "unavailable"; see vane.run.SettleCurveCheck); None otherwise.
operating_point_residual (OperatingPointResidualAudit or None) – The physical acceptance audit, when the check was enabled.
sim_time (float or None) – The as-run sim_time (TMax) setting, extended above the campaign base when a trim that ran out of time was retried; None keeps the deck’s value.
failure_mode (str or None) – The final attempt’s classified failure; None when it converged.
attempt_history (tuple[LinearizationAttempt, ...]) – The per-attempt records of the retry ladder (see LinearizationAttempt).
fallback_overrides (dict[str, object] or None) – For a case whose final attempt ran the retry policy’s final_fallback, the as-run values of its fallback_fields; None otherwise.
radiation_fit (dict[str, object] or None) – The state-space radiation file generated in the case copy (vane.run.RadiationFitRecord.to_dict(): the .ss path, the WAMIT .1 source, the state count and the per-entry fit errors); None when none was generated.
settle_assessed (bool | None)
settle_converged (bool | None)
settle_translational_velocity_rms (float | None)
settle_angular_velocity_rms (float | None)
settle_time (float | None)
settle_iterations (int | None)
settle_attempts (tuple[SettleAttempt, ...] | None)

name: str

wind_speed: float

rotor_speed_rpm: float

blade_pitch_deg: float

case_dir: str

returncode: int

succeeded: bool

n_lin: int

attempts: int = 1

converged: bool = True

trim_tol: float = 0.0

twr_kdmp: float = 0.0

bld_kdmp: float = 0.0

trim_gain_torque: float = 0.0

trim_gain_pitch: float = 0.0

settle_assessed: bool | None = None

settle_converged: bool | None = None

settle_translational_velocity_rms: float | None = None

settle_angular_velocity_rms: float | None = None

settle_time: float | None = None

settle_iterations: int | None = None

settle_attempts: tuple[SettleAttempt, ...] | None = None

settle_criterion: str | None = None

settle_confirmation: SettleConfirmation | None = None

settle_curve_rotor_speed_rpm: float | None = None

settle_curve_pitch_deg: float | None = None

settle_curve_status: str | None = None

operating_point_residual: OperatingPointResidualAudit | None = None

sim_time: float | None = None

failure_mode: str | None = None

attempt_history: tuple[LinearizationAttempt, ...] = ()

fallback_overrides: dict[str, object] | None = None

radiation_fit: dict[str, object] | None = None

class LinearizationAcceptancePolicy(max_mean_translational_speed=0.001, max_mean_angular_speed=0.0001, min_rotating_azimuths=12)[source]

Bases: object

Physical residual limits for a floating operating point.

Parameters:

max_mean_translational_speed (float) – Maximum norm of the azimuth-mean platform translational velocity, in m/s.
max_mean_angular_speed (float) – Maximum norm of the azimuth-mean platform angular velocity, in rad/s.
min_rotating_azimuths (int) – Minimum number of distinct azimuth samples needed to distinguish periodic motion from secular drift for a rotating point. The default is 12 and values below four are prohibited so blade-passing motion cannot alias into the mean. A non-rotating point needs only one linearization.

max_mean_translational_speed: float = 0.001

max_mean_angular_speed: float = 0.0001

min_rotating_azimuths: int = 12

class LinearizationAttempt(attempt, failure_mode, reason, openfast_message, failure_time, returncode, n_lin, log_file, trim_tol, twr_kdmp, bld_kdmp, trim_gain_torque, trim_gain_pitch, sim_time, tmax, fallback=False)[source]

Bases: object

The record of one OpenFAST run of an operating point’s retry ladder.

Parameters:

attempt (int) – The 1-based attempt number.
failure_mode (str or None) – The classified failure (an OpenFastFailureMode value, or "physical_residual_rejected" when the acceptance check rejected a completed run). None when the attempt converged and was accepted.
reason (str or None) – A one-line description of the failure; None on success.
openfast_message (str) – The relevant excerpt of OpenFAST’s output (its fatal error message, or its last lines); empty when none applies.
failure_time (float or None) – The simulation time (s) of OpenFAST’s fatal error, when it reported one.
returncode (int) – The OpenFAST exit status (124 for a run killed by the timeout).
n_lin (int) – The number of full-system .lin files the attempt wrote.
log_file (str or None) – The file in the case directory holding the attempt’s full OpenFAST standard output and error, <deck stem>.attempt<k>.log; None if it could not be written.
trim_tol (float) – The attempt’s trim tolerance, trim damping and effective trim gains.
twr_kdmp (float) – The attempt’s trim tolerance, trim damping and effective trim gains.
bld_kdmp (float) – The attempt’s trim tolerance, trim damping and effective trim gains.
trim_gain_torque (float) – The attempt’s trim tolerance, trim damping and effective trim gains.
trim_gain_pitch (float) – The attempt’s trim tolerance, trim damping and effective trim gains.
sim_time (float or None) – The attempt’s sim_time setting (None keeps the deck’s TMax).
tmax (float or None) – The TMax the attempt’s configured deck actually carried, when readable.
fallback (bool) – Whether the attempt ran with the retry policy’s final_fallback settings.

attempt: int

failure_mode: str | None

reason: str | None

openfast_message: str

failure_time: float | None

returncode: int

n_lin: int

log_file: str | None

trim_tol: float

twr_kdmp: float

bld_kdmp: float

trim_gain_torque: float

trim_gain_pitch: float

sim_time: float | None

tmax: float | None

fallback: bool = False

class LinearizationDriver(fst_path, output_dir, settings=<factory>, executable='openfast', template_root=None, link_inputs=True, template_copy='referenced', validate=True, retry_policy=<factory>, trim_tuning=None, acceptance_policy=None, auto_configuration=None)[source]

Bases: object

Generate, run, and collect linearizations across operating points.

Parameters:

fst_path (pathlib.Path) – The template case’s primary .fst deck.
output_dir (pathlib.Path) – Directory under which per-operating-point case directories are created. Must not be inside template_root (nor contain it), to avoid a recursive copy.
settings (LinearizationSettings) – Linearization tuning applied to every case.
executable (str or pathlib.Path) – OpenFAST executable name or path.
template_root (pathlib.Path or None) – Directory the case is copied from per operating point; defaults to fst_path’s parent. Set to a higher directory when the deck references files outside its own folder so those are copied too. File paths relative to it are preserved in each case directory.
link_inputs (bool) – When True (the default), each case is created by hard-linking the template files rather than copying their bytes, so a sweep’s heavy read-only inputs (e.g. WAMIT hydrodynamic data, airfoil tables) are shared at the inode level and a many-point sweep does not duplicate hundreds of megabytes per point. Each case still gets its own complete tree and its own outputs; the small deck files are edited via FastInputFile.write()’s atomic replace, which breaks the link so the template is never modified. Falls back to a full byte copy automatically when hard-linking is unsupported (e.g. the output directory is on a different filesystem from the template). Set to False to always copy.
template_copy ({"referenced", "tree"}) – What each case receives from template_root. "referenced" (the default) copies only the files the deck references, found recursively from the primary deck (deck_file_closure()); unrelated cases and stale outputs elsewhere under the root are left behind. When that walk cannot vouch for completeness (a relative reference outside template_root, an unreadable input) the whole tree is copied instead, with a logged warning. "tree" always copies the whole template tree.
validate (bool) – When True (the default), each configured case is checked with validate_deck() before OpenFAST is launched, so a deck that cannot linearize as configured (a DLL controller, active waves, missing state-space files, …) is rejected up front instead of failing late inside a long settle/trim run. Set to False to skip the pre-flight check.
trim_tuning (TrimTuningPolicy or None) – When set, each operating point’s starting trim settings are tuned for its wind-speed region (tune_trim_settings()) before the retry ladder runs: an at/above-rated point starts from the looser-tolerance, higher-damping floors that such points need, so it is more likely to converge on the first attempt instead of after a reactive retry. None (the default) starts every point from settings unchanged. Tuning only raises the per-case trim_tol/twr_kdmp/bld_kdmp toward the floors, so provenance is unaffected.
acceptance_policy (LinearizationAcceptancePolicy or None) – Optional post-run physical check for a floating operating point. When set, VANE averages the ElastoDyn platform-rate states over the azimuth sweep and rejects a nominally successful trimmed or explicit-time result with excessive secular translational or angular drift. This rejection is not sent through the normal retry ladder because that ladder loosens TrimTol and would make a residual drift worse; the caller must tighten the base trim or improve the warm start.
auto_configuration (dict[str, object] or None) – The record of values inferred from the deck and curve (set by vane.run.run_operating_sweep()), copied into provenance().
retry_policy (LinearizationRetryPolicy)

Raises:

ValueError – If fst_path is not within template_root, or output_dir and template_root are nested in one another.

fst_path: Path

output_dir: Path

settings: LinearizationSettings

executable: str | Path = 'openfast'

template_root: Path | None = None

link_inputs: bool = True

template_copy: TemplateCopyMode = 'referenced'

validate: bool = True

retry_policy: LinearizationRetryPolicy

trim_tuning: TrimTuningPolicy | None = None

acceptance_policy: LinearizationAcceptancePolicy | None = None

auto_configuration: dict[str, object] | None = None

case_dir(operating_point)[source]

Return the case directory for an operating point.

Parameters:: operating_point (OperatingPoint)
Return type:: Path

validated_workspace_dir(name)[source]

Return output_dir/name, rejecting one that overlaps the template tree.

A workspace directory (a linearization case or an auxiliary settle case) that is, contains, or sits inside the template root would have the template deleted by the clean-copy step, which removes the destination first. This is possible when the template lives under the output workspace and a generated name collides with a template directory. Reject any such overlap up front with a clear error, so directory creation can never destroy the source tree.

Parameters:: name (str) – The directory name to create under output_dir.
Returns:: pathlib.Path – The resolved, validated destination directory.
Raises:: ValueError – If the destination is, contains, or is inside the template root, or name is a device name Windows reserves (CON, NUL, COM1, …, with or without an extension).
Return type:: Path

generate_case(operating_point)[source]

Copy the template case and configure it for an operating point.

Parameters:: operating_point (OperatingPoint) – The operating point to set up.
Returns:: pathlib.Path – The configured primary .fst deck inside the new case directory.
Return type:: Path

run_case(operating_point, *, timeout=None)[source]

Generate, run, and collect one operating point.

Parameters:

operating_point (OperatingPoint) – The operating point to run.
timeout (float or None, optional) – Per-run timeout in seconds.

Returns:

SweepCase – The generated case and its run outcome.

Raises:

vane.run.DeckValidationError – If validate is set and the configured deck cannot be linearized (raised before OpenFAST is launched).

Return type:

SweepCase

Notes

Called directly, an unexpected exception (a file-system error while the case is copied or configured, say) propagates. Within run_sweep() the same exception is instead recorded as a failed case (see there).

run_sweep(operating_points, *, timeout=None, max_workers=None, strict=False)[source]

Run a whole sweep of operating points.

Each operating point is an independent OpenFAST run in its own case directory, so a sweep can run several points concurrently. OpenFAST itself is single-threaded here, so max_workers processes use max_workers cores; on a multi-core workstation the sweep wall-time approaches that of a single operating point rather than their sum.

Parameters:

operating_points (Sequence[OperatingPoint]) – The operating points to run, in order.
timeout (float or None, optional) – Per-run timeout in seconds.
max_workers (int or None, optional) – Number of operating points to run concurrently. None (the default) uses default_max_workers(), reserving one CPU for the machine. Results are returned in the input order regardless.
strict (bool, optional) – When True, raise SweepCaseError once every case has finished if any case raised an unexpected exception; all the cases are attached as its cases. Default False: such a case is only recorded and logged.

Returns:

list[SweepCase] – One result per operating point, in the input order.

Raises:

SweepCaseError – With strict=True, after all the cases have finished, when a case raised an unexpected exception.
ValueError – If two operating points map to the same case directory, a case directory would overlap the template root or use a reserved device name, or max_workers is less than 1. Names are compared case-insensitively (casefold), because the default Windows and macOS filesystems are case insensitive and two such cases would otherwise share – and delete – one directory. All such checks run up front, before any case is launched.
vane.run.DeckValidationError – If validate is set and a configured deck cannot be linearized: an input error found before that case’s OpenFAST run is launched.

Return type:

list[SweepCase]

Notes

One operating point never discards the others. An OpenFAST failure is classified and retried (see LinearizationRetryPolicy); an unexpected exception while a case is generated, run or collected – a file-system error that outlasted the transient-error retry, an unreadable sub-file – ends that point’s retry ladder and is recorded as a failed case: converged is False, failure_mode is "case_error" (CASE_ERROR), the final LinearizationAttempt carries the exception type and message as its reason (and so does the provenance record), its attempt log holds the traceback, and the result’s return code is -1. The earlier attempts’ records are kept. The argument checks listed under Raises are boundary errors and are still raised, the ValueError ones before any case is copied or launched.

provenance(cases, *, timestamp=None)[source]

Build a reproducibility record for a completed sweep.

Records the LinearizationSettings every case was configured with, the library version and executable, and each case’s outcome, so the conditions a set of .lin files was produced under travel with them.

The recorded settings and executable are taken from the cases’ own snapshots (frozen when each case ran), not from the driver’s current attributes, so the record stays faithful even if the driver was reconfigured after the sweep.

Parameters:

cases (Sequence[SweepCase]) – The cases returned by run_sweep() (or run_case()).
timestamp (datetime.datetime or None, optional) – The time to record; defaults to the current UTC time.

Returns:

RunProvenance – The settings, environment, and per-case record for the sweep.

Raises:

ValueError – If the cases differ on a campaign-wide setting (anything other than the per-case retry-escalated trim tolerance/damping) or on the executable, so no single run configuration describes them.

Return type:

RunProvenance

class LinearizationRetryPolicy(max_attempts=4, trim_tol_factor=3.0, damping_factor=2.0, min_retry_damping=5000.0, trim_gain_factor=4.0, pitch_trim_gain_factor=0.2, tmax_factor=2.0, max_sim_time=3600.0, early_failure_time=1.0, damping_backoff_factor=0.5, adaptive=True, final_fallback=<function above_rated_torque_trim>, fallback_modes=frozenset({OpenFastFailureMode.DIVERGENCE, OpenFastFailureMode.MOTORING, OpenFastFailureMode.ROTOR_OVERSPEED}), fallback_fields=('above_rated_trim', ))[source]

Bases: object

Adaptive retry ladder for OpenFAST linearization failures.

A case is retried when OpenFAST exits non-zero, when a rotating CalcSteady run returns fewer full-system .lin files than NLinTimes or logs that it forced the linearization, or when the run times out. Each failed attempt is classified (classify_openfast_output()) and the next attempt’s settings are chosen from that failure, starting from the failed attempt’s own settings so that successive remedies compose (next_attempt_settings()):

trim not converged (the forced single .lin): the trim ran out of time. TMax is extended to min(TMax * tmax_factor, max_sim_time) and TrimTol is loosened by trim_tol_factor, but not beyond PERIODIC_TRIM_TOL (1e-2) unless it already was: a looser trim stops on a rotor speed that is not periodic enough for MBC3. The pitch trim gain is lowered by pitch_trim_gain_factor: near rated, the IEA 15- and 22-MW pitch trims oscillate without settling at the default gain and converge at about 1e-4 rad/(rad/s). The torque gain and the trim damping are left alone: raising the gain makes a slow trim diverge, and the damping biases the trimmed point and, on every reference deck it was tried on (IEA 3.4-MW, IEA 15-MW semi), made the rotor motor within 0.3 s.
non-periodic sweep: every .lin was written but the rotor speed varies across the azimuth files by more than MBC3 accepts (a loosened TrimTol let a drifting response through). TrimTol is tightened back to the base value and TMax is extended as for a trim that ran out of time.
motoring (u%HSS_Spd is negative): the trim overshot. The pitch gain is multiplied by pitch_trim_gain_factor and the torque gain divided by trim_gain_factor. When the failure happens within early_failure_time of the start, the trim damping itself destabilised the (light) blades, so it is removed (twr_kdmp = bld_kdmp = 0); otherwise it is kept.
rotor overspeed and divergence: the gains are backed off as for motoring and the trim damping is multiplied by damping_backoff_factor (removed for an early failure).
initialisation error: an input problem. The case is not retried.
timeout, an incomplete explicit-time sweep, or an unrecognised non-zero exit: the generic escalation, which loosens TrimTol by trim_tol_factor, raises the trim damping to max(previous, min_retry_damping) * damping_factor, multiplies the torque trim gain by trim_gain_factor and the pitch trim gain by pitch_trim_gain_factor.

A too-low torque gain is a common cause of a below-rated trim failure (per Jonkman), which is why the generic step raises it. The pitch trim is a PI law whose proportional gain is 1000 * TrimGain, so an above-rated failure is usually overshoot into a growing oscillation, and every remedy except the time extension lowers that gain. Exhaustion returns the final failed result so callers still get the captured diagnostics.

Parameters:

max_attempts (int) – Total OpenFAST runs per operating point, including the first (default 4). Most failed attempts are cheap: a divergence fails within seconds, and only a trim that runs out of time uses its whole TMax.
trim_tol_factor (float) – Factor that loosens TrimTol on a trim-not-converged or generic retry.
damping_factor (float) – Factor that raises the trim damping on a generic retry.
min_retry_damping (float) – Floor the trim damping is raised to before damping_factor applies on a generic retry.
trim_gain_factor (float) – Factor that raises the torque trim gain on a generic retry, and divides it on a motoring, overspeed or divergence retry.
pitch_trim_gain_factor (float) – Factor (below one by default) that multiplies the pitch trim gain on every retry except a trim-not-converged one.
tmax_factor (float) – Factor (at least one) that extends TMax on a trim-not-converged retry. The extended value is written as sim_time; 1 disables the extension.
max_sim_time (float) – Cap (s) on the extended TMax. A deck already longer than the cap is never shortened.
early_failure_time (float) – A motoring, overspeed or divergence failure at or before this simulation time (s) is attributed to the trim damping, which the next attempt removes.
damping_backoff_factor (float) – Factor in [0, 1] that lowers the trim damping after a later overspeed or divergence.
adaptive (bool) – True (the default) chooses each retry from the classified failure. False uses the fixed schedule of settings_for_attempt(), which applies the generic escalation on every retry whatever the failure. An initialisation error is never retried in either mode.
final_fallback (callable or None) – A last resort for a trim that the gain and damping remedies cannot stabilise. The default, above_rated_torque_trim(), switches an at/above-rated point from pitch to torque trim at the curve’s pitch; None disables it. When set, the last attempt (max_attempts) that follows a failure in fallback_modes runs with final_fallback(settings), where settings is what the ladder would otherwise have chosen (so removed damping or an extended TMax carry over). It must return a LinearizationSettings that differs from its argument only in retry-escalated fields and fallback_fields. The attempt is flagged fallback=True in SweepCase.attempt_history.
fallback_modes (frozenset[OpenFastFailureMode]) – The failures that trigger final_fallback; by default the unstable-trim modes (motoring, rotor overspeed and divergence).
fallback_fields (tuple[str, ...]) – The LinearizationSettings fields final_fallback may change beyond the retry-escalated ones. They are treated as per-case values, excluded from the campaign-wide provenance comparison and recorded per case in CaseProvenance.fallback_overrides.

max_attempts: int = 4

trim_tol_factor: float = 3.0

damping_factor: float = 2.0

min_retry_damping: float = 5000.0

trim_gain_factor: float = 4.0

pitch_trim_gain_factor: float = 0.2

tmax_factor: float = 2.0

max_sim_time: float = 3600.0

early_failure_time: float = 1.0

damping_backoff_factor: float = 0.5

adaptive: bool = True

final_fallback()

Return settings with at/above-rated points trimmed by generator torque.

The default LinearizationRetryPolicy.final_fallback. A pitch trim that the gain and damping remedies cannot stabilise (large rotors near rated, where the trim’s PI loop oscillates until the rotor motors) is replaced by a torque trim at the operating point’s pitch, which converges like a below-rated point. A below-rated point already uses torque trim, so the switch leaves it unchanged.

Parameters:: settings (LinearizationSettings) – The settings the retry ladder chose for the final attempt.
Returns:: LinearizationSettings – A copy with above_rated_trim="torque".
Return type:: LinearizationSettings

fallback_modes: frozenset[OpenFastFailureMode] = frozenset({OpenFastFailureMode.DIVERGENCE, OpenFastFailureMode.MOTORING, OpenFastFailureMode.ROTOR_OVERSPEED})

fallback_fields: tuple[str, ...] = ('above_rated_trim',)

settings_for_attempt(base, attempt)[source]

Return the fixed (non-adaptive) settings for a 1-based attempt number.

Attempt 1 is base unchanged. Attempt k > 1 is k - 1 generic escalation steps from base:

trim_tol = min(base * trim_tol_factor**(k-1), MAX_TRIM_TOL); the clamp is logged and the as-run value is recorded per case in the provenance;
twr_kdmp/bld_kdmp = max(base, min_retry_damping) * damping_factor**(k-1), so every retry raises the damping above both the base and the floor;
torque trim gain = base * trim_gain_factor**(k-1);
pitch trim gain = base * pitch_trim_gain_factor**(k-1).

The driver follows this schedule when adaptive is False.

Parameters:

base (LinearizationSettings) – The operating point’s starting settings.
attempt (int) – The 1-based attempt number, at most max_attempts.

Returns:

LinearizationSettings – The settings for that attempt.

Raises:

ValueError – If attempt is not an integer in [1, max_attempts] or the escalation leaves the finite positive range.

Return type:

LinearizationSettings

next_attempt_settings(base, previous, diagnosis, *, attempt, previous_tmax=None)[source]

Return the settings for the retry that follows a classified failure.

Parameters:

base (LinearizationSettings) – The operating point’s starting settings (used by the fixed schedule).
previous (LinearizationSettings) – The settings of the attempt that failed; adaptive remedies start here.
diagnosis (OpenFastDiagnosis) – The classified failure of that attempt.
attempt (int) – The 1-based number of the attempt being configured, in [2, max_attempts].
previous_tmax (float or None, optional) – The TMax the failed attempt actually ran with (read from its deck). The extension starts from it when previous.sim_time is unset, and from MIN_CALC_STEADY_TMAX when neither is known.

Returns:

LinearizationSettings or None – The next attempt’s settings, or None when the failure is not retriable (an initialisation error or a non-finite linearization).

Raises:

ValueError – If attempt is not an integer in [2, max_attempts].

Return type:

LinearizationSettings | None

uses_fallback(diagnosis, *, attempt)[source]

Return whether attempt runs with the final_fallback settings.

Parameters:

diagnosis (OpenFastDiagnosis) – The classified failure of the previous attempt.
attempt (int) – The 1-based number of the attempt being configured.

Returns:

bool – True when a fallback is configured, attempt is the last one (max_attempts, at least 2) and the failure is retriable and one of fallback_modes.

Return type:

bool

class RunProvenance(vane_version, created_at, executable, settings, cases, auto_configuration=None)[source]

Bases: object

Reproducibility record for a linearization sweep.

Captures the exact LinearizationSettings applied to every case — so the settings a set of .lin files was produced under are recorded alongside them, not just remembered — together with the library version, the executable, and the per-case outcome.

Parameters:

vane_version (str) – Version of the library that drove the sweep.
created_at (str) – ISO-8601 timestamp of when the record was made.
executable (str) – The OpenFAST executable name or path used.
settings (dict[str, object]) – Every LinearizationSettings field and its value.
cases (tuple[CaseProvenance, ...]) – Per-operating-point provenance, in run order.
auto_configuration (dict[str, object] or None, optional) – The values vane.run.run_operating_sweep() inferred from the deck and curve, each with its source, and the warnings raised while inferring them (see vane.run.AutoConfiguration); None when nothing was inferred.

vane_version: str

created_at: str

executable: str

settings: dict[str, object]

cases: tuple[CaseProvenance, ...]

auto_configuration: dict[str, object] | None = None

to_dict()[source]

Return the record as a JSON-serializable dictionary.

Return type:: dict[str, object]

write(path)[source]

Write the record to path as JSON and return the path written.

Parameters:: path (str | Path)
Return type:: Path

class SweepCase(operating_point, case_dir, fst_path, result, settings=<factory>, base_settings=<factory>, executable='openfast', attempts=1, converged=True, operating_point_residual=None, attempt_history=(), fallback_fields=(), radiation_fit=None)[source]

Bases: object

The generated case and run outcome for one operating point.

Parameters:

operating_point (OperatingPoint) – The operating point this case was generated for.
case_dir (pathlib.Path) – The per-operating-point directory the case was copied into.
fst_path (pathlib.Path) – The configured primary .fst deck inside case_dir.
result (OpenFastResult) – The OpenFAST run outcome (return code, .lin files, output).
settings (LinearizationSettings) – A snapshot of the as-run settings this case was configured with (the final retry attempt’s, so a retried case carries its escalated trim/damping), frozen at run time so provenance reflects what actually produced the case even if the driver is later mutated.
base_settings (LinearizationSettings) – A snapshot of the campaign base settings this case escalated from (the driver’s settings at run time, before any per-case retry escalation). Frozen at run time so the campaign-wide configuration provenance records is independent of any later driver mutation. For an unretried case this equals settings.
executable (str) – The OpenFAST executable used for this case, captured at run time.
attempts (int) – How many OpenFAST runs the retry ladder used to produce this result (1 when the first run converged). The case carries the final attempt’s outcome.
converged (bool) – Whether the final attempt converged: OpenFAST exited successfully, produced the requested number of full-system .lin files, did not force the linearization without finding the steady state, and every .lin file holds only finite numbers. False means the ladder was exhausted without a trustworthy linearization for this point.
operating_point_residual (OperatingPointResidualAudit or None) – Optional independent six-DOF platform-drift audit. None when the driver’s physical acceptance check was disabled.
attempt_history (tuple[LinearizationAttempt, ...]) – One record per OpenFAST run, in order: the classified failure, the settings it ran with and the log file holding its full output. Empty for a case built by hand rather than by LinearizationDriver.run_case().
fallback_fields (tuple[str, ...]) – The retry policy’s fallback_fields when the case ran, snapshotted so provenance reads the case with the policy that produced it even if the driver’s policy is replaced or mutated afterwards.
radiation_fit (RadiationFitRecord or None) – With hydro_radiation_fit, the state-space radiation file the final attempt generated in the case copy (vane.run.ensure_radiation_state_space()); None otherwise, or when the copy already had the file.

operating_point: OperatingPoint

case_dir: Path

fst_path: Path

result: OpenFastResult

settings: LinearizationSettings

base_settings: LinearizationSettings

executable: str = 'openfast'

attempts: int = 1

converged: bool = True

operating_point_residual: OperatingPointResidualAudit | None = None

attempt_history: tuple[LinearizationAttempt, ...] = ()

fallback_fields: tuple[str, ...] = ()

radiation_fit: RadiationFitRecord | None = None

property failure_mode: str | None: Return the final attempt’s classified failure, or None on success.

property succeeded: bool: Return whether OpenFAST exited successfully for this case.

property lin_files: list[Path]: Return the .lin files produced for this case.

property n_lin: int: Return the number of full-system .lin files produced.

exception SweepCaseError(message, *, cases, result=None)[source]

Bases: RuntimeError

Raised by a strict sweep after a case raised an unexpected exception.

A linearization sweep records an unexpected exception in one operating point (a file-system error while its case is copied or configured, say) as a failed SweepCase whose failure_mode is "case_error" and carries on with the other points. With strict=True (LinearizationDriver.run_sweep()) or strict_cases=True (vane.run.run_operating_sweep()) it then raises this error – but only after every other case has finished, with all of them attached, so no completed work is lost. The first case’s exception is chained as __cause__.

Parameters:

message (str) – The error message.
cases (list[SweepCase]) – Every case of the sweep, in input order, the failed ones included.
result (OperatingSweepResult or None, optional) – The full sweep result, when raised by vane.run.run_operating_sweep().

Return type:

None

cases

As given.

Type:: list[SweepCase]

result

As given.

Type:: OperatingSweepResult or None

default_max_workers(*, reserve_cpus=1)[source]

Return a CPU-aware default worker count for independent OpenFAST cases.

Parameters:: reserve_cpus (int)
Return type:: int

Configure an OpenFAST deck for a linearization at one operating point.

Given a primary .fst deck and an OperatingPoint, this sets the linearization controls in the primary file and the operating point in the ElastoDyn and InflowWind sub-files, following the OpenFAST recommended practice:

enable Linearize and write outputs/inputs at high precision (OutFmt);
for a rotating point, trim to a periodic steady state (CalcSteady = True) with NLinTimes azimuth snapshots, choosing torque trim below rated wind speed and pitch trim at/above it (TrimCase 2 vs 3) — the standard region split;
when explicit absolute times are supplied, disable CalcSteady and linearize at those times; otherwise a standstill / parked point takes one snapshot at time zero;
set the rotor speed and blade pitch in ElastoDyn and the steady wind speed in InflowWind, with uniform inflow (power-law shear exponent PLExp = 0) by default – the same steady uniform wind the settle run (solve_steady_state()) uses, so a settled operating point is linearized in the inflow it was settled in.

For a full floating (aero-hydro-servo-elastic) deck, LinearizationSettings.offshore() additionally makes the offshore modules linearization-compatible — still water in SeaState, state-space hydrodynamics in HydroDyn with the 2nd-order forces off, quasi-steady aero with no dynamic wake in AeroDyn, and a trim-compatible ServoDyn (the Bladed-style DLL controller is not linearizable, so CalcSteady’s trim replaces it, with region-aware generator torque — zero below rated, constant above). For a trimmed rotating point the generator DOF (GenDOF) is also ensured on, since the trim regulates rotor speed through it. These edits are skipped for any module a deck does not have, so an onshore deck is unaffected.

The deck and its sub-files are edited in place with the format-preserving FastInputFile. For a multi-point sweep, copy the case to a per-operating-point directory first so that shared sub-files (e.g. a common InflowWind deck) are not mutated across points — the linearization driver does this.

class LinearizationSettings(n_lin_times=36, calc_steady=True, trim_tol=0.001, trim_gain_torque=100.0, trim_gain_pitch=0.0002, rated_wind_speed=None, lin_inputs=1, lin_outputs=1, module_linearizations=False, full_jacobians=False, out_fmt='ES20.11E3', twr_kdmp=0.0, bld_kdmp=0.0, sim_time=None, linearization_times=None, wave_mod=None, hydro_radiation_mode=None, hydro_excitation_mode=None, disable_second_order_hydro=False, unsteady_aero_mode=None, dynamic_wake_mode=None, trim_controller=False, wind_shear_exponent=0.0, structural_dofs=None, rated_generator_torque=None, trim_gain_torque_override=None, above_rated_trim='pitch', ua_end_radius=None, hydro_radiation_fit=False)[source]

Bases: object

Tunable settings for configuring a linearization deck.

Parameters:

n_lin_times (int) – Number of linearizations per rotor revolution for a rotating point (NLinTimes); 36 (every 10 degrees of azimuth) is the OpenFAST recommendation.
calc_steady (bool) – Whether a rotating point trims to a periodic steady state before linearizing (CalcSteady). A standstill/parked point always uses a single linearization regardless of this flag.
trim_tol (float) – Rotor-speed convergence tolerance for the trim (TrimTol). Must be positive and at most MAX_TRIM_TOL (0.1): a larger tolerance no longer distinguishes a periodic steady state from a drifting transient. The default 1e-3 applies to a 63 m rotor; the automatic sweep configuration scales a value left at this default with the rotor radius (vane.run.auto_config.scaled_trim_tol()).
trim_gain_torque (float) – Proportional trim gain used below rated wind speed (torque trim, Nm/(rad/s)). Used only when rated_generator_torque is not given; must be positive (as must trim_gain_pitch). The default 100.0 is far too low for a utility-scale turbine — per Jonkman the torque trim gain should be ~a tenth of the rated generator torque (e.g. ~4000 for the NREL 5-MW), so supplying rated_generator_torque (which derives the gain) is strongly preferred over relying on this default.
trim_gain_pitch (float) – Trim gain used at/above rated wind speed (pitch trim, rad/(rad/s)). ServoDyn’s CalcSteady trim is a PI law: each time step adds TrimGain times the rotor-speed error to an integrator, and the pitch offset adds 1000 times that error on top, so the effective proportional gain is 1000 * TrimGain and the integral gain TrimGain / DT. The default 2e-4 applies to a 63 m rotor (the NREL 5-MW, which oscillates or motors above rated at 1e-3); the automatic sweep configuration scales a value left at this default with the rotor radius (vane.run.auto_config.scaled_trim_gain_pitch()).
above_rated_trim ({"pitch", "torque"}) – How CalcSteady trims an at/above-rated point. "pitch" (default, the documented OpenFAST practice) holds the generator torque constant and trims blade pitch. "torque" holds the blade pitch at the operating point’s value (the user’s rotor-performance curve) and trims generator torque with the torque gain, exactly as below rated. Torque trim converges where a pitch trim oscillates (large rotors near rated, e.g. the IEA 15- and 22-MW); the linearized plant is the same open-loop model at the curve’s pitch and rotor speed, and the trimmed torque’s departure from rated measures how far the curve and the deck disagree (see verify_operating_points()). The retry ladder switches to "torque" as its final fallback. ServoDyn’s flattened law stays engaged: in its region 3 the torque is the constant VS_RtTq with zero speed derivative, and the trim adds its offset on top, so the generator torque is one constant (VS_RtTq + offset) exactly as below rated (0 + offset), the linearized plant is unchanged, and the trim starts from rated torque rather than from zero.
rated_generator_torque (float or None) – Rated generator torque in N·m. When given, the torque trim gain is derived from it as rated_generator_torque / 10 (Jonkman’s rule of thumb), overriding trim_gain_torque; this is the dependable way to get a torque trim that converges below rated. It also supplies the constant generator torque (VS_RtTq) the above-rated pitch trim needs when trim_controller is on. None (default) falls back to trim_gain_torque for the gain and to the deck’s VS_RtTq for the torque – but only when the deck’s original VSContrl is 1 (the simple variable-speed law actually in use); a DLL or other controller deck carries a placeholder VS_RtTq, so an above-rated trimmed point on it requires this value. This value is preserved across retry attempts.
trim_gain_torque_override (float or None) – An explicit, already-resolved torque trim gain (Nm/(rad/s)) that takes precedence over both rated_generator_torque and trim_gain_torque in resolved_trim_gain_torque(). Set by the retry ladder (LinearizationRetryPolicy) to pin an escalated gain without discarding rated_generator_torque (which still drives VS_RtTq); normally left None.
rated_wind_speed (float or None) – Wind speed (m/s) separating the below-rated (torque-trim) and above-rated (pitch-trim) control regions of the turbine being linearized (e.g. 11.4 for the NREL 5-MW, about 10.6 for the IEA 15-MW). There is no turbine-independent default: it is required for any rotating point whose trim or controller handling depends on the region (calc_steady or trim_controller), and a clear error is raised when it is missing.
lin_inputs (int) – LinInputs switch (0=none, 1=standard, 2=all).
lin_outputs (int) – LinOutputs switch (0=none, 1=from OutList, 2=all). 1 is required for the load/QoI channels to appear in C/D.
module_linearizations (bool) – Set LinOutMod so OpenFAST writes per-module linearization files alongside the full-system files. This is required for module-specific physics models, including MoorDyn driven directly by measured fairlead kinematics.
full_jacobians (bool) – Set LinOutJac so OpenFAST also writes the unassembled module Jacobians. OpenFAST requires lin_inputs=lin_outputs=2 when this debug export is enabled. It is useful for auditing the exact module coupling paths used by a subsystem digital twin.
out_fmt (str) – Output number format (OutFmt); a high precision such as "ES20.11E3" is important for accurate eigenvalues.
twr_kdmp (float) – Tower and blade artificial damping used only during the steady-state trim.
bld_kdmp (float) – Tower and blade artificial damping used only during the steady-state trim.
sim_time (float or None) – TMax to set. None leaves the deck’s value unchanged, except that a CalcSteady trim is given at least MIN_CALC_STEADY_TMAX (600 s): a template deck’s placeholder TMax would end the trim before it converges. OpenFAST stops as soon as the trim converges, so the floor costs nothing.
linearization_times (tuple[float, ...] or None) – Absolute OpenFAST times in seconds at which to linearize when calc_steady=False. The values must be finite, non-negative, strictly increasing, no later than sim_time when it is supplied, and their count must equal n_lin_times. None retains the single-snapshot untrimmed behaviour. This path is intended for a rotating plant that has already been demonstrated to be at periodic equilibrium by an independent physical check.
wave_mod (int or None) – SeaState WaveMod to set (0 = still water, required for linearization). None leaves the deck unchanged. Setting still water also neutralises the wave options it leaves meaningless but that OpenFAST would reject: WaveDirMod and ConstWaveMod are set to 0 (required for any linearization), a wave-stretching model other than 0/1 (WaveStMod) is set to 0, MacCamy-Fuchs diffraction (MCFD) to 0, and a DEFAULT sub-surface current heading (CurrSSDir) is replaced by the deck’s WaveDir so the current keeps its direction.
hydro_radiation_mode (int or None) – HydroDyn RdtnMod / ExctnMod to set. Linearization rejects the convolution/DFT models, so use 0 (none) or 2 (state-space, which needs the .ss / .ssexctn files). None leaves the deck unchanged. When either is set and HydroDyn then requires RdtnDT to equal the glue-code DT (WAMIT potential flow with a radiation or state-space excitation model) but the deck holds another numeric step, RdtnDT is set to DEFAULT.
hydro_excitation_mode (int or None) – HydroDyn RdtnMod / ExctnMod to set. Linearization rejects the convolution/DFT models, so use 0 (none) or 2 (state-space, which needs the .ss / .ssexctn files). None leaves the deck unchanged. When either is set and HydroDyn then requires RdtnDT to equal the glue-code DT (WAMIT potential flow with a radiation or state-space excitation model) but the deck holds another numeric step, RdtnDT is set to DEFAULT.
hydro_radiation_fit (bool) – Generate a missing <PotFile>.ss radiation file in each linearization case copy from the WAMIT .1 data (vane.run.ensure_radiation_state_space()) before the case is validated and run; the template is never written, and the fit is recorded per case in the run provenance. Requires hydro_radiation_mode = 2. Default False. run_operating_sweep() sets it when its automatic configuration finds the file missing but the WAMIT data fittable within the acceptance limit.
disable_second_order_hydro (bool) – Zero HydroDyn’s 2nd-order force switches (MnDrift/NewmanApp/ DiffQTF/SumQTF) and switch off SeaState’s 2nd-order wave kinematics (WvDiffQTF/WvSumQTF), which linearization does not support.
unsteady_aero_mode (int or None) – AeroDyn UA_Mod to set; linearization requires 0 (quasi-steady) or 4/5/6. None leaves the deck unchanged. On a legacy-format AeroDyn deck (AFAeroMod/UAMod/WakeMod keywords), 0 sets AFAeroMod = 1 (steady airfoil aerodynamics), the only value that format can linearize; a linearizable unsteady model (4–6) cannot be expressed there and is reported by validate_deck().
dynamic_wake_mode (int or None) – AeroDyn DBEMT_Mod to set; linearization requires -1 (frozen), 0 (none), or 3. None leaves the deck unchanged. On a legacy-format AeroDyn deck, -1/0 replace a dynamic-BEMT wake (WakeMod = 2, not linearizable in that format) with plain BEMT (WakeMod = 1) and set the FrozenWake flag to True/False respectively; 3 cannot be expressed there and is reported by validate_deck().
ua_end_radius (float or None) – AeroDyn UAEndRad to set: the blade-radius fraction beyond which unsteady aerodynamics is switched off, in (0, 1]. None (the default) leaves the deck unchanged. AeroDyn keeps unsteady aerodynamics on every node whose radius fraction is not greater than UAEndRad, so UAEndRad = 1 keeps it on at the blade-tip node. With the Prandtl tip loss model that node’s inflow is fixed (full axial induction), and its unsteady-aerodynamics states can turn NaN or infinite in the linearization. A value below 1 (e.g. 0.99) ends unsteady aerodynamics inboard of the tip. The AeroDyn file must contain a UAEndRad line; a modern-format file without one is rejected before any file is written. Legacy-format files get the value only when they have the line.
trim_controller (bool) – Make ServoDyn trim-compatible (PCMode = 0, VSContrl = 1, HSSBrMode = 0, YCMode = 0, GenTiStr = GenTiStp = True, and a GenModel other than 1/2 reset to 1): the Bladed-style DLL controller is not linearizable, so CalcSteady’s own trim replaces it. For a trimmed rotating point the generator torque is then set up per region: below rated the generator is kept off (GenTiStr/TimGenOn beyond TMax) so the torque trim owns it; at/above rated the simple variable-speed law is flattened to a constant torque (VS_RtGnSp/VS_Rgn2K/VS_SlPc tiny, VS_RtTq set from rated_generator_torque when given, else the deck’s existing VS_RtTq) so the pitch trim converges. Flattening requires a positive constant torque; an above-rated point with neither rated_generator_torque nor a positive deck VS_RtTq is rejected (it would otherwise trim against zero torque). The deck VS_RtTq is trusted only when the deck’s original VSContrl is 1: a DLL-controlled deck (VSContrl = 5) or any other non-simple law carries a placeholder (e.g. 9999.9), so an above-rated point on such a deck without rated_generator_torque is rejected rather than trimmed at a wrong torque.
wind_shear_exponent (float or None) – InflowWind power-law shear exponent (PLExp) to write. The default 0.0 is steady uniform inflow, the convention of the settle run (solve_steady_state()), so a settled point is linearized in the same inflow it settled in; run_operating_sweep() passes this value to its settle runs too. None leaves the deck’s PLExp unchanged. Recorded with the other settings in the run provenance.
structural_dofs (dict[str, bool] or None) – ElastoDyn structural-DOF flags to set in the ED sub-file (e.g. {"YawDOF": False, "DrTrDOF": False}). None (the default) applies the linearization defaults: the blade and tower flexibility DOFs (FLEXIBILITY_DOFS: FlapDOF1, FlapDOF2, EdgeDOF, TwFADOF1, TwFADOF2, TwSSDOF1, TwSSDOF2) are enabled, so a deck shipped with rigid blades or tower still linearizes its blade and tower modes, and YawDOF and DrTrDOF are disabled. Disabling YawDOF removes the spurious free nacelle-yaw rigid-body mode (there is no yaw controller in a linearization); disabling DrTrDOF drops the drivetrain-torsion mode (~0.62 Hz) but improves CalcSteady trim convergence — a deliberate tradeoff. Supply a mapping to override: it is merged on top of the defaults, so {"DrTrDOF": True} re-enables the drivetrain-torsion mode while still disabling YawDOF, and {} keeps only the defaults. A flag the user explicitly lists but the ED deck lacks is an error; a default flag the deck lacks is silently skipped (the deck variant simply has no such DOF).

Notes

The module fields default to leave the deck unchanged (None / False), so an onshore or already-prepared deck is unaffected — except structural_dofs, whose None default disables YawDOF/DrTrDOF for a reliable linearization. For a full floating (aero-hydro-servo-elastic) deck, build the linearization-compatible set in one call with offshore().

n_lin_times: int = 36

calc_steady: bool = True

trim_tol: float = 0.001

trim_gain_torque: float = 100.0

trim_gain_pitch: float = 0.0002

rated_wind_speed: float | None = None

lin_inputs: int = 1

lin_outputs: int = 1

module_linearizations: bool = False

full_jacobians: bool = False

out_fmt: str = 'ES20.11E3'

twr_kdmp: float = 0.0

bld_kdmp: float = 0.0

sim_time: float | None = None

linearization_times: tuple[float, ...] | None = None

wave_mod: int | None = None

hydro_radiation_mode: int | None = None

hydro_excitation_mode: int | None = None

disable_second_order_hydro: bool = False

unsteady_aero_mode: int | None = None

dynamic_wake_mode: int | None = None

trim_controller: bool = False

wind_shear_exponent: float | None = 0.0

structural_dofs: dict[str, bool] | None = None

rated_generator_torque: float | None = None

trim_gain_torque_override: float | None = None

above_rated_trim: str = 'pitch'

ua_end_radius: float | None = None

hydro_radiation_fit: bool = False

is_below_rated(wind_speed)[source]

Return whether wind_speed lies in the below-rated (torque-trim) region.

Parameters:: wind_speed (float) – Operating-point wind speed (m/s).
Returns:: bool – True below rated_wind_speed, False at or above it.
Raises:: ValueError – If rated_wind_speed is not set.
Return type:: bool

resolved_trim_gain_torque()[source]

Return the torque trim gain (Nm/(rad/s)) to write into TrimGain.

An explicit trim_gain_torque_override (pinned by the retry ladder) takes precedence. Otherwise, when rated_generator_torque is given, the gain is derived from it as rated_generator_torque * 0.1 (Jonkman’s rule of thumb — a too-low torque trim gain is the most common cause of CalcSteady non-convergence below rated); otherwise the explicit trim_gain_torque is used.

Returns:: float – The torque trim gain to apply below rated wind speed.
Return type:: float

resolved_structural_dofs()[source]

Return the ElastoDyn DOF flags to apply, defaults merged with overrides.

The linearization defaults (blade and tower flexibility enabled, YawDOF and DrTrDOF disabled) are the base; a user-supplied structural_dofs mapping is merged on top, so an override re-enables or adds flags while the un-overridden defaults remain.

Returns:: dict[str, bool] – The effective ElastoDyn DOF-flag map (flag name -> enabled).
Return type:: dict[str, bool]

explicit_structural_dofs()[source]

Return the DOF-flag names the user explicitly requested (not just defaults).

A user-listed flag must exist in the ED deck (its absence is an error); a flag present only via the defaults is skipped when the deck lacks it.

Returns:: frozenset[str] – The flag names supplied in structural_dofs (empty when None).
Return type:: frozenset[str]

snapshot()[source]

Return a fully independent copy, deep-copying the mutable fields.

dataclasses.replace shallow-copies, so a plain replace snapshot would share the same structural_dofs dict object as the source. A later mutation of the source’s (or the originally-supplied) dict would then also mutate the snapshot, breaking snapshot independence. This copies the mutable structural_dofs mapping so the returned settings are decoupled from any later mutation.

Returns:: LinearizationSettings – A copy whose mutable fields share no object with this instance.
Return type:: LinearizationSettings

classmethod offshore(**overrides)[source]

Return settings prepared for a floating aero-hydro-servo-elastic deck.

Enables the full linearization-compatible module set — still water, state-space hydrodynamics, quasi-steady aero with a frozen wake (DBEMT_Mod = -1, valid for linearization across OpenFAST versions), the 2nd-order forces off and the controller replaced by the trim — that lets a real FOWT deck linearize. No trim damping is set: Twr_Kdmp/Bld_Kdmp do work on the periodic blade and tower motion and bias the trimmed operating point (the IEA 10-MW’s trimmed generator torque came out about 8 % low at 4 m/s with 5000 N/(m/s)), and on light blades they can destabilise the start of the trim. The retry ladder adds damping only when a trim keeps running out of time. Keyword overrides replace any of these fields (e.g. twr_kdmp=5000.0, bld_kdmp=5000.0 to trim with damping from the first attempt).

Parameters:: **overrides (object) – Field values to override on the returned settings (e.g. hydro_radiation_mode=0 when no .ss file is available).
Returns:: LinearizationSettings – Settings with the offshore module configuration enabled.
Return type:: LinearizationSettings

configure_linearization(deck_path, operating_point, settings=None, *, confine_to=None)[source]

Configure an OpenFAST deck for linearization at an operating point.

Edits the primary .fst and its sub-files in place.

Parameters:

deck_path (str or pathlib.Path) – Path to the primary .fst deck (its sub-files are edited too).
operating_point (OperatingPoint) – The operating point to set up.
settings (LinearizationSettings or None, optional) – Linearization tuning; defaults are used when None.
confine_to (str or pathlib.Path or None, optional) – When given, every input these settings edit must resolve inside this directory (see require_inputs_within()); the sweep driver passes each case copy so a shared sub-file is never modified, while files that are only read may stay shared.

Raises:

vane.io.FastInputError – If a required keyword (e.g. Linearize) is absent from the deck, the operating point requests a positive wind speed but the deck has no usable InflowWind file to set it in (which would silently linearize in still air), or an edited input lies outside confine_to.

Return type:

None

Notes

For a multi-point sweep, copy the case to a per-operating-point directory first so shared sub-files are not mutated across points. The template deck is assumed to already enable the structural/aero/control modules appropriate for the case (CompElast/CompAero/CompServo); this sets the linearization controls, the operating point, and — for a non-zero wind point — CompInflow so the configured wind is actually used.

is_size_scaled_default(value)[source]

Return whether a trim setting is still the class default (not user-given).

Parameters:: value (float) – LinearizationSettings.trim_tol or trim_gain_pitch.
Returns:: bool – True when the value is the untouched class default, which the automatic sweep configuration scales with the rotor radius; False for any value passed explicitly, even one equal to the default.
Return type:: bool

needs_rated_wind_speed(settings, deck_path)[source]

Return whether a rotating point on this deck needs rated_wind_speed.

The region split selects the CalcSteady trim case, and the ServoDyn generator handling under trim_controller. It is therefore needed when calc_steady is on, or when trim_controller is on and the deck’s ServoDyn is enabled; a disabled ServoDyn (CompServo = 0) is never configured, so it needs no region.

Parameters:

settings (LinearizationSettings) – The linearization settings.
deck_path (str or pathlib.Path) – The primary .fst deck.

Returns:

bool – True when a rotating operating point requires the rated wind speed.

Return type:

bool

require_inputs_within(deck_path, root, *, keys=None)[source]

Reject a deck whose edited sub-files resolve outside root.

Linearization and settle runs edit the primary deck and some of its sub-files. A sub-file referenced outside the per-case copy (e.g. ../ElastoDyn.dat when the copy root is the deck’s own directory) would be edited where it lives – a file shared by every case and the template – so such a deck is rejected before anything is written. A sub-file that is only read may stay shared.

Parameters:

deck_path (str or pathlib.Path) – The primary .fst deck.
root (str or pathlib.Path) – Directory every edited input must resolve inside (the case copy).
keys (Sequence[str] or None, optional) – The sub-file keywords that will be edited. None checks every file a linearization may edit (ElastoDyn, InflowWind, AeroDyn, ServoDyn, HydroDyn, SeaState), except the file of a module the deck switches off (CompAero, CompServo, CompHydro or CompSeaSt = 0).

Raises:

vane.io.FastInputError – If the deck or an edited sub-file resolves outside root.

Return type:

None

Pre-flight validation that a deck will actually linearize, before running it.

An OpenFAST linearization fails late and obscurely when the deck holds a module configuration linearization does not support — a Bladed-style DLL controller (which has no Jacobian), wave excitation, convolution radiation, or a state-space hydrodynamics model whose .ss / .ssexctn coefficient files are missing. A long settle and trim run then aborts with a terse solver error.

validate_deck() checks the effective configuration — the deck as it will be after the LinearizationSettings edits are applied — and reports every blocking problem at once, before any OpenFAST process is launched. It is a guard, not a fixer: it never edits the deck. Settings that neutralise a problem (e.g. trim_controller replacing the DLL, or wave_mod=0 forcing still water) clear the corresponding check, so a raw FOWT template paired with LinearizationSettings.offshore() passes, while the same template run with default settings is rejected with an actionable message.

The checks mirror the linearization restrictions OpenFAST enforces in its glue code and modules (see the Linearization restrictions reference page). A module the primary deck switches off (CompServo, CompSeaSt, CompHydro, CompAero, CompMooring, CompElast, CompInflow = 0 or another module choice) leaves its input file inert, so that file is not inspected.

OPENFAST_MAX_PATH_LENGTH = 258

Longest full path, in characters, the Windows OpenFAST build opens a file by.

Windows’ classic MAX_PATH is 260 characters including the terminating null. The Intel-Fortran OpenFAST build is not long-path aware and does not collapse ..: on OpenFAST v5.0.0 an input opened as <working dir>\.\..\5MW_Baseline\<file> of 258 characters was read and one of 259 characters failed with The input file ... was not found.

exception DeckPathLengthError[source]

Bases: DeckValidationError

Raised when OpenFAST would open a deck file by a path that is too long.

See check_deck_path_lengths().

exception DeckValidationError[source]

Bases: ValueError

Raised when a deck cannot be linearized as configured.

The message lists every blocking problem found, one per line, so the deck can be fixed in a single pass rather than one error per run.

check_deck_path_lengths(deck_path, *, max_length=258)[source]

Reject a deck whose sub-files OpenFAST would open by an over-long path.

OpenFAST builds every sub-file path by joining the referencing file’s directory, as it spelled it, to the reference – without collapsing ... Started from the deck’s directory on the deck’s bare name (as run_openfast() does), a deck that keeps shared files next to it in ../Shared/ therefore opens them as <deck dir>\.\..\Shared\<file>, and a nested reference inherits the whole chain. The operating system receives that string appended to the working directory. When it exceeds the Windows path limit the file cannot be opened and OpenFAST aborts at initialisation with The input file ... was not found, although the file exists.

This check walks the deck’s references (deck_file_closure()) and spells each one as OpenFAST will, before any process is launched.

Parameters:

deck_path (str or pathlib.Path) – The primary .fst deck, in the directory OpenFAST will be run from.
max_length (int, optional) – Longest permitted full path in characters. Default OPENFAST_MAX_PATH_LENGTH.

Raises:

DeckPathLengthError – If any file would be opened by a path longer than max_length; the message names the longest such path and its length.
FileNotFoundError – If deck_path is not an existing file.

Return type:

None

Notes

The limit applies to Windows builds that are not long-path aware, which is why run_openfast() runs this check only on Windows. A reference the walk cannot follow (an unreadable input) is skipped with a debug log rather than failing the check; OpenFAST will report it itself.

validate_deck(deck_path, settings=None)[source]

Reject a deck that will not linearize as configured, before running it.

Validates the configuration that will be in force once settings is applied: a problem the settings neutralise (the DLL controller replaced by the trim, waves forced to still water) does not fail the check, but a genuinely non-linearizable state that nothing fixes does. The checks cover the module choices OpenFAST cannot linearize (SED, AeroDisk, ExtLoads, FEAMooring, OrcaFlex, ice and soil modules), the CalcSteady azimuth step, InflowWind (lidar, upflow), ServoDyn (control modes, generator model, timed generator start/stop), SeaState (waves, spreading, constrained waves, 2nd-order kinematics, still-water consistency), HydroDyn (potential-flow model, radiation/excitation models and their files, 2nd-order forces, additional body DOFs, radiation time step), AeroDyn (wake, unsteady-aero, and dynamic-wake models, unsteady aerodynamics reaching the blade-tip node under tip loss, nacelle drag), BeamDyn (pitch actuator), and MoorDyn (VIV and viscoelastic lines).

Parameters:

deck_path (str or pathlib.Path) – Path to the primary .fst deck. Its sub-files are inspected when present and their module is enabled; an onshore deck without them is fine.
settings (LinearizationSettings or None, optional) – The settings that will be applied before running. Defaults to LinearizationSettings (all module fields “leave unchanged”), so a deck that is already linearization-ready passes and a raw one is judged as-is.

Raises:

DeckValidationError – If one or more blocking problems are found (all are reported together).
vane.io.FastInputError – If deck_path cannot be read at all.

Return type:

None

Proactive per-operating-point trim auto-tuning for the linearization sweep.

The CalcSteady trim that finds a turbine’s periodic steady state before linearizing is hardest at and above rated wind speed: thrust is high and the platform/tower response is lightly damped, so a tolerance and trim damping that converge an easy below-rated point often stall a near-/above-rated one. LinearizationRetryPolicy recovers from that reactively — it adapts the tolerance, TMax, trim gains and damping to the classified failure after a run has already failed, costing one or more wasted OpenFAST runs per hard point.

This module sets those same knobs proactively. Given an operating point and the campaign-base LinearizationSettings, tune_trim_settings() returns the settings to start that point from, applying the documented above-rated trim floors — a looser TrimTol and a trim-damping floor on Twr_Kdmp/Bld_Kdmp — to points at or above rated so they are likely to converge on the first attempt. It only ever raises tolerance/damping toward those floors, never tightens below the campaign base, and below-rated and standstill points are returned unchanged, so the tuner can only help. The reactive retry ladder still escalates from the tuned starting point for any residual hard case.

The tuner adjusts only the three fields the retry ladder already treats as per-case (trim_tol, twr_kdmp, bld_kdmp), so a sweep’s run provenance — which records those per case and compares the rest campaign-wide — is unaffected. The below/above-rated boundary is the settings’ own rated_wind_speed, the same split configure_linearization() uses to choose torque vs pitch trim.

class TrimTuningPolicy(above_rated_trim_tol=0.01, above_rated_damping=5000.0)[source]

Bases: object

Floors applied to the trim settings of an at/above-rated operating point.

Parameters:

above_rated_trim_tol (float) – Minimum rotor-speed trim tolerance (TrimTol) to use at or above rated wind speed. A point’s tolerance is raised to this floor (never lowered below the campaign base); below-rated points keep the base tolerance. The default 1e-2 is the loosened tolerance the above-rated trim needs (the base default is 1e-3). It must not exceed MAX_TRIM_TOL (0.1), and the retry ladder that escalates from it clamps there too.
above_rated_damping (float) – Minimum artificial trim damping (Twr_Kdmp and Bld_Kdmp) to use at or above rated wind speed; the point’s damping is raised to this floor. The damping acts only during the steady-state trim and is stripped from the linearized model, but it can bias the trimmed operating point slightly, so use the smallest floor that converges. The default 5000 matches the offshore preset’s trim damping.

above_rated_trim_tol: float = 0.01

above_rated_damping: float = 5000.0

tune_trim_settings(operating_point, base, policy)[source]

Return the trim settings to start one operating point from.

For a rotating point that trims (CalcSteady) at or above the base settings’ rated_wind_speed, the trim tolerance and tower/blade trim damping are raised to the policy’s floors (whichever is larger — the campaign base is never tightened). A below-rated point, or a standstill/parked point that takes a single linearization without a trim, is returned unchanged.

Parameters:

operating_point (OperatingPoint) – The operating point whose starting trim settings to compute.
base (LinearizationSettings) – The campaign-base settings.
policy (TrimTuningPolicy) – The above-rated trim floors to apply.

Returns:

LinearizationSettings – A copy of base with the above-rated trim floors applied when they raise the knobs, or an unchanged copy otherwise.

Return type:

LinearizationSettings

Verify a linearization’s trimmed operating point against rotor-performance data.

VANE does not compute rotor performance: the user supplies the steady operating schedule (wind speed, rotor speed, blade pitch and, optionally, the power and thrust coefficients) and OpenFAST’s CalcSteady trims the turbine about it. Below rated it trims the generator torque at the prescribed pitch and rotor speed; above rated it trims the blade pitch at constant generator torque. Whether the trimmed point agrees with the supplied curve is a direct consistency check on the curve and the deck: a large mismatch points to a wrong curve, rotor radius, air density, gearbox ratio or drivetrain loss, or a deck/curve inconsistency.

This module reads the trimmed operating point back out of the .lin files of each linearization (inputs first, outputs as a fallback), derives the aerodynamic power from the steady low-speed-shaft torque balance and compares rotor speed, pitch, power coefficient and (when the outputs carry the rotor thrust) thrust coefficient with the curve, each against a documented tolerance.

Torque balance

At a periodic steady state the azimuth-mean rotor acceleration vanishes, so the mean aerodynamic torque on the low-speed shaft equals the shaft torque transmitted to the gearbox. ElastoDyn relates the low-speed-shaft torque \(Q_{LSS}\) to the high-speed-shaft generator torque \(Q_g\) through the gearbox ratio \(N\) and efficiency \(\eta\),

\[Q_{LSS} = N\,Q_g\,\eta^{-\operatorname{sgn}(Q_g \Omega)},\]

so that losses reduce the generator torque when power flows rotor to generator and increase the required shaft torque when the generator motors the rotor. The aerodynamic power and power coefficient are then

\[P = Q_{LSS}\,\Omega, \qquad C_p = \frac{P}{\tfrac12 \rho \pi R^2 U^3}.\]

The generator (electrical) efficiency does not enter: Q_g is the mechanical torque on the high-speed shaft. Bearing friction and any other drivetrain loss not modelled by GBoxEff are neglected.

The balance also assumes nothing else acts on the rotor. CalcSteady’s artificial trim damping (Twr_Kdmp/Bld_Kdmp) does: on the IEA 10-MW sweep, trimmed with 5000 N/(m/s), it absorbed 8 % of the rotor torque at 4 m/s (OpenFAST v4.0.5: AeroDyn power 436.6 kW against 396.7 kW from the balance; 1.3 % apart when the same point is trimmed without damping, AeroDyn’s power unchanged). When the deck beside the .lin files has non-zero trim damping, the aerodynamic power is therefore AeroDyn’s own rotor power (RtFldPwr/RtAeroPwr) when the outputs carry it.

class OperatingPointCheck(label, trimmed, aero_power, rotor_speed, pitch, cp, ct, issues=(), power_source='torque balance')[source]

Bases: object

The verification of one trimmed operating point.

Parameters:

label (str) – Identifies the operating point (a sweep case name or the set index).
trimmed (TrimmedOperatingPoint) – The trimmed point read from the .lin files.
aero_power (float) – Aerodynamic rotor power, in W, from the low-speed-shaft torque balance, or AeroDyn’s own rotor power when trim damping makes the balance invalid (see power_source).
rotor_speed (QuantityCheck) – Rotor speed (rpm) against the curve.
pitch (QuantityCheck) – Blade pitch (deg) against the curve.
cp (QuantityCheck) – Power coefficient against the curve.
ct (QuantityCheck) – Thrust coefficient against the curve (unavailable without a rotor-thrust output or a curve ct).
issues (tuple[str, ...]) – Notes on missing data, including the trimmed point’s own issues.
power_source (str) – Where aero_power comes from: "torque balance" or the AeroDyn output channel ("output: AD RtFldPwr").

label: str

trimmed: TrimmedOperatingPoint

aero_power: float

rotor_speed: QuantityCheck

pitch: QuantityCheck

cp: QuantityCheck

ct: QuantityCheck

issues: tuple[str, ...] = ()

power_source: str = 'torque balance'

property checks: dict[str, QuantityCheck]: Return the four checks keyed by quantity name.

property status: Literal['pass', 'flag', 'incomplete']

Return "flag" if any check fails, "incomplete" if data is missing.

A point is "incomplete" when no check fails but its rotor speed or pitch could not be compared, or the trimmed data carries an issue. A curve that simply lacks cp/ct does not make a point incomplete.

property flagged_quantities: tuple[str, ...]: Return the names of the quantities outside tolerance.

class OperatingPointVerification(points, constants, tolerances, skipped=<factory>)[source]

Bases: object

The trimmed-versus-curve verification of a set of linearizations.

Parameters:

points (tuple[OperatingPointCheck, ...]) – One check per verified operating point, in input order.
constants (TurbineConstants) – The turbine constants used.
tolerances (TrimTolerances) – The tolerances applied.
skipped (tuple[str, ...], optional) – Operating points that could not be verified (e.g. a non-converged sweep case), each with its reason.

points: tuple[OperatingPointCheck, ...]

constants: TurbineConstants

tolerances: TrimTolerances

skipped: tuple[str, ...]

property passed: bool: Return whether every verified point passes and none was skipped.

property flagged: tuple[OperatingPointCheck, ...]: Return the points with at least one quantity outside tolerance.

to_records()[source]

Return one flat record per point, e.g. for a pandas.DataFrame.

Returns:: list[dict[str, float or str or None]] – Keys: label, wind_speed, generator_torque, aero_power, power_source, aerodyn_power, trim_damping, rotor_thrust, status, and for each of rotor_speed, pitch, cp and ct the <q>, <q>_curve, <q>_deviation and <q>_status entries.
Return type:: list[dict[str, float | str | None]]

to_table()[source]

Return a plain-text table of the verification.

Returns:: str – One row per point: wind, rotor speed (trimmed/curve), pitch (trimmed/curve/deviation), generator torque, aerodynamic power, Cp (trimmed/curve/relative deviation), Ct (likewise) and the status.
Return type:: str

class QuantityCheck(trimmed, curve, tolerance, relative)[source]

Bases: object

One trimmed quantity compared with the curve.

Parameters:

trimmed (float) – The value at the trimmed operating point (NaN if unavailable).
curve (float) – The curve value at the trimmed wind speed (NaN if unavailable).
tolerance (float) – The tolerance applied.
relative (bool) – Whether tolerance bounds the relative (True) or absolute deviation.

trimmed: float

curve: float

tolerance: float

relative: bool

property deviation: float: Return trimmed - curve.

property relative_deviation: float: Return (trimmed - curve) / |curve| (NaN when the curve is zero).

property status: Literal['pass', 'flag', 'unavailable']: Return "pass", "flag" or "unavailable".

class RotorPerformanceCurve(wind_speed, rotor_speed_rpm, blade_pitch_deg, cp=None, ct=None)[source]

Bases: object

A user-supplied steady rotor-performance schedule.

Parameters:

wind_speed (tuple[float, ...]) – Strictly increasing hub-height wind speeds, in m/s.
rotor_speed_rpm (tuple[float, ...]) – Rotor speed at each wind speed, in rpm.
blade_pitch_deg (tuple[float, ...]) – Collective blade pitch at each wind speed, in degrees.
cp (tuple[float, ...] or None, optional) – Aerodynamic power coefficient at each wind speed (NaN where unknown), or None when the curve carries no power coefficient.
ct (tuple[float, ...] or None, optional) – Rotor thrust coefficient at each wind speed (NaN where unknown), or None when the curve carries no thrust coefficient.

Raises:

ValueError – If the arrays differ in length, have fewer than two samples, contain a non-finite wind, rotor speed or pitch, or the wind speeds are not strictly increasing.

wind_speed: tuple[float, ...]

rotor_speed_rpm: tuple[float, ...]

blade_pitch_deg: tuple[float, ...]

cp: tuple[float, ...] | None = None

ct: tuple[float, ...] | None = None

classmethod from_arrays(wind_speed, rotor_speed_rpm, blade_pitch_deg, *, cp=None, ct=None)[source]

Build a curve from array-likes, e.g. operating_curve_from_csv output.

Parameters:

wind_speed (Sequence[float]) – The required schedule, in m/s, rpm and degrees.
rotor_speed_rpm (Sequence[float]) – The required schedule, in m/s, rpm and degrees.
blade_pitch_deg (Sequence[float]) – The required schedule, in m/s, rpm and degrees.
cp (Sequence[float] or None, optional) – Optional power and thrust coefficients.
ct (Sequence[float] or None, optional) – Optional power and thrust coefficients.

Returns:

RotorPerformanceCurve – The validated curve.

Return type:

RotorPerformanceCurve

at(wind_speed)[source]

Interpolate the curve at one wind speed.

The same shape-preserving monotone cubic (PCHIP) used to build sweep operating points from a curve is used here, without extrapolation.

Parameters:: wind_speed (float) – Hub-height wind speed, in m/s.
Returns:: dict[str, float] – rotor_speed_rpm, blade_pitch_deg, cp and ct; a value is NaN outside the curve’s range or when the curve lacks that quantity (a coefficient needs at least two finite samples).
Return type:: dict[str, float]

class TrimTolerances(rotor_speed_rel=0.01, pitch_deg=0.5, cp_rel=0.05, ct_rel=0.05)[source]

Bases: object

Tolerances of the trimmed-versus-curve comparison.

The defaults reflect what a correct deck/curve pair achieves on the reference turbines (rotor speed exact, pitch within a few tenths of a degree, power coefficient within a few percent): a looser agreement is worth investigating.

Parameters:

rotor_speed_rel (float, optional) – Relative rotor-speed tolerance (default 0.01, i.e. 1 %).
pitch_deg (float, optional) – Absolute blade-pitch tolerance, in degrees (default 0.5).
cp_rel (float, optional) – Relative power-coefficient tolerance (default 0.05).
ct_rel (float, optional) – Relative thrust-coefficient tolerance (default 0.05).

Raises:

ValueError – If a tolerance is negative or non-finite.

rotor_speed_rel: float = 0.01

pitch_deg: float = 0.5

cp_rel: float = 0.05

ct_rel: float = 0.05

class TrimmedOperatingPoint(wind_speed, rotor_speed_rpm, blade_pitch_deg, blade_pitch_spread_deg, generator_torque, n_lin, pitch_source=None, generator_torque_source=None, rotor_thrust=None, rotor_thrust_source=None, aerodyn_power=None, issues=(), aerodyn_power_source=None, trim_damping=None)[source]

Bases: object

The operating point OpenFAST trimmed to, read from one linearization’s files.

Every quantity is the mean over the azimuth files of the set (and, for pitch, over the blades).

Parameters:

wind_speed (float) – Hub-height wind speed, in m/s.
rotor_speed_rpm (float) – Rotor speed, in rpm.
blade_pitch_deg (float) – Blade pitch, mean over blades and azimuths, in degrees (NaN if absent).
blade_pitch_spread_deg (float) – Largest minus smallest pitch over blades and azimuths, in degrees (NaN if absent). A trimmed collective pitch has zero spread.
generator_torque (float) – High-speed-shaft generator torque, in N m (NaN if absent).
n_lin (int) – Number of .lin files in the set.
pitch_source (str or None) – The channel the pitch was read from, or None.
generator_torque_source (str or None) – The channel the generator torque was read from, or None.
rotor_thrust (float or None) – AeroDyn rotor aerodynamic thrust along the shaft, in N, when the outputs carry it; else None.
rotor_thrust_source (str or None) – The output channel the thrust was read from.
aerodyn_power (float or None) – AeroDyn rotor aerodynamic power, in W, when the outputs carry it; an independent check on the torque-balance power.
issues (tuple[str, ...]) – Human-readable notes on anything missing or inconsistent.
aerodyn_power_source (str or None) – The output channel aerodyn_power was read from.
trim_damping (float or None) – The larger of the Twr_Kdmp and Bld_Kdmp trim-damping factors, in N/(m/s), of the <root>.fst deck beside the files (0.0 when CalcSteady is off); None when that deck cannot be read. Non-zero trim damping absorbs rotor torque, so the torque balance no longer gives the aerodynamic power (see verify_operating_points()).

wind_speed: float

rotor_speed_rpm: float

blade_pitch_deg: float

blade_pitch_spread_deg: float

generator_torque: float

n_lin: int

pitch_source: str | None = None

generator_torque_source: str | None = None

rotor_thrust: float | None = None

rotor_thrust_source: str | None = None

aerodyn_power: float | None = None

issues: tuple[str, ...] = ()

aerodyn_power_source: str | None = None

trim_damping: float | None = None

class TurbineConstants(gearbox_ratio, gearbox_efficiency, rotor_radius, air_density)[source]

Bases: object

Turbine constants the torque balance and coefficients need.

Parameters:

gearbox_ratio (float) – Gearbox ratio \(N\) (high-speed over low-speed shaft speed), positive.
gearbox_efficiency (float) – Gearbox efficiency \(\eta\) as a fraction in (0, 1] (ElastoDyn’s GBoxEff is in percent; from_deck() converts it).
rotor_radius (float) – Rotor radius \(R\) used to normalize the coefficients, in m.
air_density (float) – Air density \(\rho\), in kg/m^3.

Raises:

ValueError – If any constant is non-finite or non-positive, or the efficiency exceeds one.

gearbox_ratio: float

gearbox_efficiency: float

rotor_radius: float

air_density: float

property rotor_area: float: Return the swept area \(\pi R^2\), in m^2.

classmethod from_deck(fst_path, *, radius_convention='projected')[source]

Read the constants from an OpenFAST deck.

The gearbox ratio (GBRatio, or GBoxRatio for Simplified-ElastoDyn), gearbox efficiency (GBoxEff, percent; 100 % when absent), tip radius (TipRad) and precone (PreCone(i) or PreCone) are read from the structural (EDFile) input; this holds for BeamDyn decks too, whose rotor geometry still lives in ElastoDyn. The air density is AeroDyn’s AirDens, or the .fst AirDens when AeroDyn’s is "default" or absent.

Parameters:

fst_path (str or pathlib.Path) – The primary .fst deck.
radius_convention ({"projected", "tip"}, optional) – "projected" (default) normalizes with the rotor-plane radius TipRad * cos(PreCone), the swept-area radius most blade-element tools use; "tip" uses TipRad itself. Pass explicit constants when a curve was normalized with some other radius.

Returns:

TurbineConstants – The constants.

Raises:

ValueError – If a required value is missing or non-numeric, or radius_convention is unknown.

Return type:

TurbineConstants

aerodynamic_power(generator_torque, rotor_speed_rpm, constants)[source]

Return the aerodynamic rotor power from the steady torque balance.

Parameters:

generator_torque (float) – High-speed-shaft generator torque, in N m.
rotor_speed_rpm (float) – Rotor speed, in rpm.
constants (TurbineConstants) – Supplies the gearbox ratio and efficiency.

Returns:

float – \(N Q_g \Omega \eta^{-\operatorname{sgn}(Q_g\Omega)}\), in W: the gearbox loss is added back when power flows rotor to generator and subtracted when the generator motors the rotor.

Return type:

OperatingPointVerification

rotor_performance_from_csv(path)[source]

Read a rotor-performance CSV, including its optional coefficient columns.

The required wind_speed, rotor_speed_rpm and blade_pitch_deg columns are parsed, unit-converted and validated exactly as by operating_curve_from_csv() (unit-annotated headers such as wind_speed [m/s] are accepted). The optional power-coefficient column (cp, power_coefficient, RtAeroCp, RtFldCp) and thrust-coefficient column (ct, thrust_coefficient, RtAeroCt, RtFldCt) are read as well; a blank or non-numeric coefficient cell becomes NaN (unknown) rather than an error.

The coefficients are returned as fractions. A coefficient column’s unit is read from its header bracket, as for the required columns: no unit, [-], [1] or [fraction] means a fraction, and [%], [percent] or [pct] a percentage, which is divided by 100. Any other unit is rejected. So is a scale that contradicts the declared unit: a fraction above the physical bound (the Betz limit 16/27 for cp, 2 for ct), which is what a percentage written without its unit looks like, and a column declared in percent whose non-zero values are all at most 1 in magnitude, which reads as fractions labelled as percent. A separate units row is not supported.

Parameters:

path (str or pathlib.Path) – Path to the rotor-performance CSV.

Returns:

RotorPerformanceCurve – The curve, sorted by ascending wind speed.

Raises:

FileNotFoundError – If path does not exist.
ValueError – As operating_curve_from_csv(); if more than one column matches the power or thrust coefficient; or if a coefficient column has an unsupported unit or a scale that contradicts its unit (see above).

Return type:

RotorPerformanceCurve

trimmed_operating_point(lin_files)[source]

Read the trimmed operating point from one linearization’s .lin files.

The blade pitch is read from the ElastoDyn pitch-command inputs (ED Blade <i> pitch command, the same for ElastoDyn and BeamDyn blades), or the collective pitch-command input; the generator torque from the ED Generator torque input. When the inputs are absent (LinInputs = 0) the ED BldPitch<i> and SrvD GenTq outputs are used instead. Wind and rotor speed come from each file’s header. Every quantity is averaged over the azimuth files.

Parameters:: lin_files (Sequence[LinFile or str or os.PathLike]) – The full-system .lin files of one linearization (one per azimuth), parsed or as paths.
Returns:: TrimmedOperatingPoint – The trimmed point; a quantity that cannot be found is NaN and explained in TrimmedOperatingPoint.issues.
Raises:: ValueError – If lin_files is empty.
Return type:: TrimmedOperatingPoint

verify_operating_points(lin_sets, curve, *, deck=None, constants=None, radius_convention='projected', tolerances=None, labels=None)[source]

Verify the trimmed operating points of linearizations against a curve.

For each linearization (its set of azimuth .lin files) the trimmed wind, rotor speed, blade pitch and generator torque are read back (trimmed_operating_point()), the aerodynamic power is derived from the steady low-speed-shaft torque balance (aerodynamic_power()) and the power coefficient \(C_p = P / (\tfrac12\rho\pi R^2U^3)\) formed. The thrust coefficient is formed only when the outputs carry AeroDyn’s rotor thrust (RtFldFxh or RtAeroFxh in the AeroDyn OutList). Each quantity is compared with the curve interpolated at the trimmed wind speed.

Below rated, CalcSteady prescribes the rotor speed and pitch from the curve, so their agreement is by construction and \(C_p\) (from the trimmed torque) is the informative check; above rated the trimmed pitch is.

When the deck beside a set’s files trimmed with artificial damping (non-zero Twr_Kdmp/Bld_Kdmp with CalcSteady), the damping absorbs part of the rotor torque and the generator torque no longer balances the aerodynamic torque. The power is then AeroDyn’s rotor power output when present (OperatingPointCheck.power_source says which was used); without it the balance is kept and a warning logged.

Parameters:

lin_sets (Sequence[Sequence[LinFile or str or os.PathLike]]) – One entry per operating point: the .lin files of that linearization.
curve (RotorPerformanceCurve or str or pathlib.Path or tuple) – The user’s rotor-performance data. A path is read with rotor_performance_from_csv() (so its cp/ct columns are used); a 3-tuple such as operating_curve_from_csv() returns carries no coefficients, so only rotor speed and pitch are compared.
deck (str or pathlib.Path or None, optional) – An .fst deck of the turbine, read for the constants (TurbineConstants.from_deck()). Required unless constants is given.
constants (TurbineConstants or None, optional) – Explicit constants; take precedence over deck.
radius_convention ({"projected", "tip"}, optional) – Radius used with deck (see TurbineConstants.from_deck()).
tolerances (TrimTolerances or None, optional) – Comparison tolerances (default TrimTolerances).
labels (Sequence[str] or None, optional) – A label per set; defaults to "ws<wind>".

Returns:

OperatingPointVerification – The per-point checks and overall outcome.

Raises:

ValueError – If neither deck nor constants is given, labels has the wrong length, a set is empty, or the deck/curve cannot be read.

Return type:

verify_sweep_operating_points(sweep, curve, *, constants=None, radius_convention='projected', tolerances=None)[source]

Verify the trimmed points of a run_operating_sweep() result.

Every converged case with .lin files is verified, labelled by its operating point’s name; a case that did not converge or produced no .lin files is listed in OperatingPointVerification.skipped. Unless constants is given, the turbine constants are read from the first verified case’s configured deck.

Parameters:

sweep (OperatingSweepResult) – The sweep result.
curve (RotorPerformanceCurve or str or pathlib.Path or tuple) – The rotor-performance data (see verify_operating_points()); pass the same CSV the sweep used to get the cp/ct comparison too.
constants (TurbineConstants or None, optional) – Explicit constants.
radius_convention ({"projected", "tip"}, optional) – Radius used when reading the constants from the deck.
tolerances (TrimTolerances or None, optional) – Comparison tolerances.

Returns:

OperatingPointVerification – The per-point checks.

Raises:

ValueError – If no case of the sweep can be verified.

Return type:

OperatingPointVerification

Post-run acceptance checks for a linearized operating point.

CalcSteady establishes periodicity according to OpenFAST’s normalized output criterion. That criterion is necessary, but a deliberately loose TrimTol can still stop while a floating platform carries a secular six-DOF drift. Such a point is parseable and can produce a finite MBC model, yet it is a poor equilibrium about which to build a small-perturbation model.

This module provides an independent physical check. It reads the ElastoDyn platform rate states from every full-system .lin file and estimates the azimuth mean of each rate component with quadrature weights that exactly annihilate the 1P, 2P and 3P harmonics at the actual sample azimuths. Periodic motion therefore cancels; a secular drift does not. The resulting translational and angular residuals can reject a nominally successful trim without mistaking ordinary once-per-revolution motion for non-convergence.

The weights are the minimum-norm solution of the harmonic moment conditions, which for seven or more samples is exactly the constant term of a least-squares fit of a mean plus 1P–3P harmonics. On an exactly uniform sweep they reduce to the equal-weight average. They remain valid for the non-uniform azimuths CalcSteady actually produces: OpenFAST takes each snapshot at the first time step at or past its target azimuth, so real sweeps are uniform only to within RotSpeed * DT.

class LinearizationAcceptancePolicy(max_mean_translational_speed=0.001, max_mean_angular_speed=0.0001, min_rotating_azimuths=12)[source]

Bases: object

Physical residual limits for a floating operating point.

Parameters:

max_mean_translational_speed (float) – Maximum norm of the azimuth-mean platform translational velocity, in m/s.
max_mean_angular_speed (float) – Maximum norm of the azimuth-mean platform angular velocity, in rad/s.
min_rotating_azimuths (int) – Minimum number of distinct azimuth samples needed to distinguish periodic motion from secular drift for a rotating point. The default is 12 and values below four are prohibited so blade-passing motion cannot alias into the mean. A non-rotating point needs only one linearization.

max_mean_translational_speed: float = 0.001

max_mean_angular_speed: float = 0.0001

min_rotating_azimuths: int = 12

class OperatingPointResidualAudit(assessed, accepted, reason, file_count, distinct_azimuths, rotating, translational_channels, angular_channels, mean_translational_velocity, mean_angular_velocity, mean_translational_speed, mean_angular_speed, max_instantaneous_translational_speed, max_instantaneous_angular_speed, max_mean_translational_speed, max_mean_angular_speed)[source]

Bases: object

Physical residual evidence extracted from one linearization sweep.

Parameters:

assessed (bool)
accepted (bool)
reason (str | None)
file_count (int)
distinct_azimuths (int)
rotating (bool)
translational_channels (tuple[str, ...])
angular_channels (tuple[str, ...])
mean_translational_velocity (tuple[float, ...] | None)
mean_angular_velocity (tuple[float, ...] | None)
mean_translational_speed (float | None)
mean_angular_speed (float | None)
max_instantaneous_translational_speed (float | None)
max_instantaneous_angular_speed (float | None)
max_mean_translational_speed (float)
max_mean_angular_speed (float)

assessed: bool

accepted: bool

reason: str | None

file_count: int

distinct_azimuths: int

rotating: bool

translational_channels: tuple[str, ...]

angular_channels: tuple[str, ...]

mean_translational_velocity: tuple[float, ...] | None

mean_angular_velocity: tuple[float, ...] | None

mean_translational_speed: float | None

mean_angular_speed: float | None

max_instantaneous_translational_speed: float | None

max_instantaneous_angular_speed: float | None

max_mean_translational_speed: float

max_mean_angular_speed: float

class PeriodicStateResidualAudit(assessed, reason, file_count, distinct_azimuths, rotating, min_rotating_azimuths, channels, excluded_rotating_channels, excluded_cyclic_channels, max_mean_to_rms_ratio)[source]

Bases: object

State-derivative residuals for a periodic OpenFAST operating point.

Rotating-frame states are excluded because their native derivatives contain the intended rotor-periodic coordinate transport. The generator-azimuth coordinate is also excluded because its derivative is the intended rotor speed; its angular acceleration state remains in the audit. No heterogeneous state units are combined into one physical norm.

Parameters:

assessed (bool)
reason (str | None)
file_count (int)
distinct_azimuths (int)
rotating (bool)
min_rotating_azimuths (int)
channels (tuple[StateDerivativeResidual, ...])
excluded_rotating_channels (tuple[str, ...])
excluded_cyclic_channels (tuple[str, ...])
max_mean_to_rms_ratio (float | None)

assessed: bool

reason: str | None

file_count: int

distinct_azimuths: int

rotating: bool

min_rotating_azimuths: int

channels: tuple[StateDerivativeResidual, ...]

excluded_rotating_channels: tuple[str, ...]

excluded_cyclic_channels: tuple[str, ...]

max_mean_to_rms_ratio: float | None

class StateDerivativeResidual(state_description, derivative_description, module, unit, mean_derivative, rms_derivative, oscillatory_rms_derivative, mean_to_rms_ratio, active)[source]

Bases: object

Azimuth statistics for one non-rotating continuous-state derivative.

mean_to_rms_ratio is dimensionless and invariant to a change of state units. It approaches zero for a resolved zero-mean periodic derivative and one for a constant secular derivative. It is None when the derivative is inactive at floating-point resolution; absolute mean_derivative and rms_derivative values are retained so this ratio is never mistaken for an engineering limit.

Parameters:

state_description (str)
derivative_description (str)
module (str)
unit (str)
mean_derivative (float)
rms_derivative (float)
oscillatory_rms_derivative (float)
mean_to_rms_ratio (float | None)
active (bool)

state_description: str

derivative_description: str

module: str

unit: str

mean_derivative: float

rms_derivative: float

oscillatory_rms_derivative: float

mean_to_rms_ratio: float | None

active: bool

audit_operating_point_residual(lin_files, policy=None)[source]

Audit secular platform drift across an OpenFAST azimuth sweep.

Paths are parsed with VANE’s strict .lin reader; already parsed LinFile objects are accepted too. If the model has no ElastoDyn platform-rate states (for example a fixed-bottom turbine), the check is not applicable and returns assessed=False, accepted=True. A rotating point with too few distinct azimuths is not accepted because an instantaneous periodic rate cannot be separated from secular drift.

Parameters:

lin_files (Sequence[path-like or LinFile]) – Full-system files from one operating point.
policy (LinearizationAcceptancePolicy or None, optional) – Residual limits; defaults to LinearizationAcceptancePolicy.

Returns:

OperatingPointResidualAudit – The component means, vector norms, thresholds, and acceptance decision.

Raises:

ValueError – If no files are supplied or their state descriptions are inconsistent.

Return type:

OperatingPointResidualAudit

audit_periodic_state_residual(lin_files, *, min_rotating_azimuths=12)[source]

Audit mean derivatives without mixing state units into a scalar norm.

The derivative operating point in each .lin file is sampled over azimuth. For every non-rotating, non-cyclic continuous state, this function reports the azimuth mean, total RMS, zero-mean oscillatory RMS, and the scale-invariant ratio abs(mean) / RMS. A resolved periodic equilibrium has a small ratio, whereas a secular derivative survives the azimuth mean. Absolute residuals must still be interpreted in their stated engineering units.

Parameters:

lin_files (Sequence[path-like or LinFile]) – Full-system files from one operating point.
min_rotating_azimuths (int, optional) – Minimum number of distinct azimuths required before the periodic statistics are assessed. The default is 12; publication campaigns should normally use 36. The denser requirement prevents a 3P component from aliasing into a three-azimuth mean.

Returns:

PeriodicStateResidualAudit – Per-state residual statistics and the explicit exclusions.

Raises:

ValueError – If no files are supplied, the requested sample count is smaller than four, or the state/derivative channel layouts disagree.

Return type:

PeriodicStateResidualAudit

Solve a floating turbine’s steady operating point by a fully-coupled settle run.

A CalcSteady linearization of a floating turbine needs good initial conditions — in particular the platform’s thrust-loaded equilibrium position — or the open-loop trim diverges near peak thrust (the rotor decelerates into a stalled, motoring state). The dependable way to obtain them is to run the fully-coupled model with its real controller at a steady wind until it settles, then read the operating point off the time series.

solve_steady_state() does exactly that: it configures the deck for a constant-wind time-domain run (still water, uniform inflow with no shear by default – the same inflow the linearization then uses – and the controller left active), runs OpenFAST, discards the initial transient, and averages the steady window to return an OperatingPoint carrying the settled rotor speed, blade pitch, and PlatformPosition. Feeding that point back into configure_linearization() (with LinearizationSettings.offshore()) starts the linearization at the true equilibrium.

The deck is edited in place, so pass a writable working copy (the linearization driver copies the case per operating point).

The settle run uses exactly the still water the linearization uses: SeaState is set to WaveMod = 0 and the wave options OpenFAST rejects in still water are neutralised by the same helper configure_linearization() applies.

Unlike the linearization, the settle run keeps the deck’s Bladed-style controller library (ServoDyn DLL_FileName) active. Published decks often point it at a library built for another platform (a Linux libdiscon.so path on Windows), so the library is checked before OpenFAST launches and a missing one fails fast; pass controller_library to point the settle copy at a library built for this host.

ConfirmTimeSource

How the length of a two-stage settle’s confirmation run was chosen.

alias of Literal[‘user’, ‘platform_period’, ‘damped_stage’, ‘fallback’]

class EquilibriumTolerances(translation_m=0.1, rotation_deg=0.05, rotor_speed_rel=0.005, pitch_deg=0.1, residual_damping_ratio=0.005, growing_damping_ratio=0.02, oscillation_velocity_rms=0.2)[source]

Bases: object

Tolerances on a change of the settled operating-point means.

Used to judge whether the undamped confirmation of a two-stage settle reproduces the damped stage’s equilibrium, and – with criterion="mean_drift" – whether a run’s means still drift between the halves of its analysis window.

Parameters:

translation_m (float, optional) – Platform surge/sway/heave, m. Default 0.1.
rotation_deg (float, optional) – Platform roll/pitch/yaw, deg. Default 0.05.
rotor_speed_rel (float, optional) – Rotor speed, relative to max(|reference rotor speed|, 1 rpm). Default 0.005.
pitch_deg (float, optional) – Collective blade pitch, deg. Default 0.1.
residual_damping_ratio (float, optional) – Smallest damping ratio at which the residual platform oscillation of an undamped confirmation counts as decaying (see SettleConfirmation.residual_damping_ratio). Default 0.005.
growing_damping_ratio (float, optional) – Classification threshold: an undamped confirmation whose residual damping ratio is below -growing_damping_ratio is clearly growing (its equilibrium is unstable under the deck’s controller), not merely sustained. Default 0.02: the amplitude then grows by exp(2 pi 0.02) - 1, about 13 %, per cycle and by a factor of about 2.7 over the eight cycles an automatically sized confirmation analyses – unmistakable growth, whereas a limit cycle, a beating of two slow modes or a controller re-exciting the platform after the restart stays above it (the IEA 15-MW semi at 12-14 m/s gives -0.007 to -0.009). It does not reject anything: with the "auto" criterion a growing oscillation about a confirmed equilibrium is accepted like a sustained one, but flagged (SettleConfirmation.growing_oscillation) and logged with its own warning (see solve_steady_state()).
oscillation_velocity_rms (float, optional) – Largest platform-velocity RMS (m/s for the translational channels, deg/s for the angular ones) of a sustained or growing oscillation the "auto" criterion accepts about a confirmed equilibrium. Default 0.2, twenty times the default settle tolerance: at a 100 s surge period about +/-4.5 m of surge, at a 30 s pitch period about +/-1.4 deg of pitch – small enough for its whole-period means to be a well-defined measurement of the equilibrium. A larger one is reported, not accepted.

Raises:

ValueError – If any tolerance is not positive and finite.

translation_m: float = 0.1

rotation_deg: float = 0.05

rotor_speed_rel: float = 0.005

pitch_deg: float = 0.1

residual_damping_ratio: float = 0.005

growing_damping_ratio: float = 0.02

oscillation_velocity_rms: float = 0.2

exceeded(changes, reference_rotor_speed_rpm)[source]

Return the quantities whose change exceeds its tolerance.

Parameters:

changes (Mapping[str, float]) – Change of each mean, keyed as SettleAttempt.mean_drift.
reference_rotor_speed_rpm (float) – The rotor speed the relative rotor-speed tolerance refers to.

Returns:

tuple of str – The names (in the order of changes) outside tolerance.

Return type:

tuple[str, …]

class SettleAttempt(translational_velocity_rms, angular_velocity_rms, assessed, converged, settle_time, iteration, window_start=None, window_end=None, stage='settle', mean_drift=None, oscillation_period=None, criterion=None, residual_damping_ratio=None)[source]

Bases: object

Convergence evidence from one adaptive settle attempt.

Each entry preserves the horizon and measured platform-velocity RMS values before a later adaptive run overwrites the OpenFAST output file.

Parameters:

translational_velocity_rms (float) – Largest RMS platform translational velocity (m/s) over the analysis window; nan when no translational-velocity channel was output.
angular_velocity_rms (float) – Largest RMS platform angular velocity (deg/s) over the analysis window; nan when no angular-velocity channel was output.
assessed (bool) – Whether any platform-velocity channel was available to judge settling.
converged (bool) – Whether every assessed velocity RMS was within tolerance.
settle_time (float) – The TMax (s) of this attempt.
iteration (int) – One-based attempt number.
window_start (float or None, optional) – Bounds (s) of the trailing analysis window this attempt was judged over, [settle_time - (initial settle_time - discard_time), settle_time]. None when not recorded.
window_end (float or None, optional) – Bounds (s) of the trailing analysis window this attempt was judged over, [settle_time - (initial settle_time - discard_time), settle_time]. None when not recorded.
stage ({"settle", "damped", "confirm"}, optional) – Which run this was: an ordinary settle run ("settle"), a run of the temporarily damped first stage of a two-stage settle ("damped"), or its undamped confirmation run ("confirm"). See solve_steady_state().
mean_drift (dict[str, float] or None, optional) – Change of each measured operating-point mean between the first and second halves of the analysis window (second minus first): surge/sway/ heave (m), roll/pitch/yaw (deg), rotor_speed_rpm and blade_pitch_deg. None when not computed.
oscillation_period (float or None, optional) – Dominant period (s) of the platform-velocity channel with the largest RMS over the analysis window – the period of whatever is still moving. None when it could not be estimated (too few samples, or no motion).
criterion ({"velocity", "mean_drift"} or None, optional) – The criterion that judged this attempt (with criterion="auto" it may differ between attempts). None when not recorded.
residual_damping_ratio (float or None, optional) – Damping ratio of the platform oscillation over the analysis window, from the cycle-by-cycle decay of the most active platform-velocity channel (positive: decaying; near zero: sustained; negative: growing). None when fewer than two whole cycles were output.

translational_velocity_rms: float

angular_velocity_rms: float

assessed: bool

converged: bool

settle_time: float

iteration: int

window_start: float | None = None

window_end: float | None = None

stage: Literal['settle', 'damped', 'confirm'] = 'settle'

mean_drift: dict[str, float] | None = None

oscillation_period: float | None = None

criterion: Literal['velocity', 'mean_drift', 'auto'] | None = None

residual_damping_ratio: float | None = None

class SettleConfirmation(damping, damped_converged, damped_translational_velocity_rms, damped_angular_velocity_rms, damped_settle_time, damped_means, confirm_means, shift, shift_flagged, confirm_converged, residual_damping_ratio, stable, confirmed, tolerances, confirm_time=None, confirm_time_source=None, extended=False, sustained_oscillation=False)[source]

Bases: object

Evidence of a two-stage settle: damped stage, then undamped confirmation.

Parameters:

damping (SettlePlatformDamping) – The temporary platform damping of the first stage.
damped_converged (bool) – Whether the damped stage met the settle criterion.
damped_translational_velocity_rms (float) – The damped stage’s final platform-velocity RMS (m/s, deg/s; nan when not measured).
damped_angular_velocity_rms (float) – The damped stage’s final platform-velocity RMS (m/s, deg/s; nan when not measured).
damped_settle_time (float) – TMax (s) of the damped stage’s final run.
damped_means (dict[str, float]) – The damped stage’s settled means (keys as SettleAttempt.mean_drift); the undamped confirmation starts from them.
confirm_means (dict[str, float]) – The undamped confirmation run’s means over its analysis window (averaged over whole periods of any residual oscillation).
shift (dict[str, float]) – confirm_means - damped_means for every quantity measured in both.
shift_flagged (tuple of str) – Quantities whose shift exceeds tolerances.
confirm_converged (bool) – Whether the undamped confirmation run met the settle criterion by itself.
residual_damping_ratio (float or None) – Damping ratio of the undamped run’s residual platform oscillation, from the decay of its cycle-by-cycle RMS: positive when it dies out, zero or negative when it is sustained or growing. None when fewer than two whole cycles were output.
stable (bool) – Whether the undamped run is stable about the equilibrium: it met the criterion by itself, or (velocity criterion) its residual oscillation decays with a damping ratio of at least tolerances.residual_damping_ratio.
confirmed (bool) – True when the undamped run reproduced the damped equilibrium within tolerances and is stable, or – sustained_oscillation – when it reproduced it while carrying a measurable sustained or growing oscillation ("auto"). Restarting an undamped model, even at its equilibrium, rings its slow modes (the controller’s start-up transient alone does), and a lightly damped mode cannot ring down within a short confirmation; a decaying residual is accepted as confirmation of a stable equilibrium. False means the damping changed the answer, or the undamped model’s oscillation could not be accepted (too large to measure its mean, too few cycles, or a criterion other than "auto").
tolerances (EquilibriumTolerances) – The tolerances applied.
confirm_time (float or None, optional) – TMax (s) of the confirmation run that was judged (the extended one when extended). None when not recorded.
confirm_time_source ({"user", "platform_period", "damped_stage", "fallback"} or None, optional) – How the first confirmation’s length was chosen: given by the caller, or sized automatically from the slowest platform period (platform_period of solve_steady_state(), e.g. the standstill platform probe’s), from the damped stage’s dominant period, or the fallback length when neither was known. None when not recorded.
extended (bool, optional) – True when the confirmation was decaying but its means had not yet returned to the damped equilibrium, so it was rerun once twice as long and that longer run was judged.
sustained_oscillation (bool, optional) – True when the point was accepted although the undamped run keeps a non-decaying oscillation: its whole-period means reproduce the damped equilibrium within tolerances, and either the mean-drift criterion accepted the run or – "auto" criterion only – the oscillation is measurable (residual damping ratio known, velocity RMS within tolerances.oscillation_velocity_rms), whether sustained or growing. Linear damping cannot move an equilibrium (it acts on the velocity, zero there), so the damped stage’s equilibrium is the undamped model’s, stable or not; it is the operating point. A growing oscillation is additionally flagged by growing_oscillation.

damping: SettlePlatformDamping

damped_converged: bool

damped_translational_velocity_rms: float

damped_angular_velocity_rms: float

damped_settle_time: float

damped_means: dict[str, float]

confirm_means: dict[str, float]

shift: dict[str, float]

shift_flagged: tuple[str, ...]

confirm_converged: bool

residual_damping_ratio: float | None

stable: bool

confirmed: bool

tolerances: EquilibriumTolerances

confirm_time: float | None = None

confirm_time_source: Literal['user', 'platform_period', 'damped_stage', 'fallback'] | None = None

extended: bool = False

sustained_oscillation: bool = False

property growing_oscillation: bool

Return whether the point was accepted with a growing oscillation.

True when sustained_oscillation holds and the residual damping ratio is below -tolerances.growing_damping_ratio: the equilibrium is unstable under the deck’s controller (the closed-loop oscillation grows without the added damping). Linear damping does not move an equilibrium, and the shift test reproduced it, so it is linearized; the linearization trims without the controller, so the controller-in-the-loop instability is not part of the linear model.

Returns:: bool – Whether the accepted confirmation’s oscillation is clearly growing.

to_dict()[source]

Return the confirmation as a dictionary, with growing_oscillation.

Returns:: dict[str, object] – Every field (as dataclasses.asdict()) plus growing_oscillation.
Return type:: dict[str, object]

class SettleConvergence(translational_velocity_rms, angular_velocity_rms, assessed, converged, settle_time, iterations, attempts=(), window_start=None, window_end=None, criterion='velocity', mean_drift=None, oscillation_period=None, confirmation=None, requested_criterion='velocity', criterion_switched=False, prescribed_rotor=False, residual_damping_ratio=None, sustained_oscillation=False)[source]

Bases: object

Whether a settle run reached equilibrium, judged by platform-velocity RMS.

Parameters:

translational_velocity_rms (float) – Largest root-mean-square platform translational velocity (m/s) over the trailing analysis window, across the output velocity channels; nan when none were output.
angular_velocity_rms (float) – Largest RMS platform angular velocity (deg/s) over the trailing analysis window; nan when no angular-velocity channel was output.
assessed (bool) – Whether any platform-velocity channel was available to judge settling. When False the run cannot be confirmed settled (the deck output no velocity).
converged (bool) – Whether every assessed velocity RMS is within tolerance (True when not assessed — nothing measured cannot fail, but assessed records that).
settle_time (float) – The TMax (s) of the run this convergence describes.
iterations (int) – How many settle runs were performed (more than one only when adaptive).
attempts (tuple of SettleAttempt) – Ordered convergence evidence for every attempted horizon. This makes an adaptive accept/reject decision reconstructible after intermediate OpenFAST output files have been overwritten.
window_start (float or None, optional) – Bounds (s) of the trailing analysis window of the final run, over which both the convergence outcome and the returned operating-point means were computed. None when not recorded.
window_end (float or None, optional) – Bounds (s) of the trailing analysis window of the final run, over which both the convergence outcome and the returned operating-point means were computed. None when not recorded.
criterion ({"velocity", "mean_drift"}, optional) – The settle criterion that judged the run: platform-velocity RMS within tolerance ("velocity", the default) or operating-point means that no longer drift between the two halves of the analysis window ("mean_drift"). With criterion="auto" this is the criterion the automatic choice settled on. See solve_steady_state().
mean_drift (dict[str, float] or None, optional) – The final run’s half-window mean drift (see SettleAttempt.mean_drift).
oscillation_period (float or None, optional) – The final run’s dominant platform-velocity period (s); see SettleAttempt.oscillation_period.
confirmation (SettleConfirmation or None, optional) – For a two-stage settle (platform_damping given), the damped stage’s evidence and the undamped confirmation’s outcome; None for an ordinary settle.
requested_criterion ({"velocity", "mean_drift", "auto"}, optional) – The criterion the caller asked for. Differs from criterion only for "auto".
criterion_switched (bool, optional) – True when criterion="auto" switched from the velocity to the mean-drift criterion because the platform carried a sustained, non-decaying oscillation the velocity criterion can never accept.
prescribed_rotor (bool, optional) – True when the settle ran without a controller, with the rotor speed and blade pitch held at their initial values (see prescribed_rotor of solve_steady_state()); the settled rotor speed and pitch are then the prescribed ones and only the platform equilibrium was found.
residual_damping_ratio (float or None, optional) – The final run’s platform-oscillation damping ratio (see SettleAttempt.residual_damping_ratio).
sustained_oscillation (bool, optional) – True when a two-stage settle was accepted with a non-decaying (sustained or growing) oscillation about its confirmed equilibrium (see SettleConfirmation.sustained_oscillation); a warning is logged.

translational_velocity_rms: float

angular_velocity_rms: float

assessed: bool

converged: bool

settle_time: float

iterations: int

attempts: tuple[SettleAttempt, ...] = ()

window_start: float | None = None

window_end: float | None = None

criterion: Literal['velocity', 'mean_drift', 'auto'] = 'velocity'

mean_drift: dict[str, float] | None = None

oscillation_period: float | None = None

confirmation: SettleConfirmation | None = None

requested_criterion: Literal['velocity', 'mean_drift', 'auto'] = 'velocity'

criterion_switched: bool = False

prescribed_rotor: bool = False

residual_damping_ratio: float | None = None

sustained_oscillation: bool = False

property growing_oscillation: bool

Return whether the point was accepted with a growing oscillation.

Returns:: bool – SettleConfirmation.growing_oscillation of the confirmation; False for a single-stage settle.

to_dict()[source]

Return the record as a dictionary, with growing_oscillation added.

Returns:: dict[str, object] – Every field (as dataclasses.asdict()), with confirmation from SettleConfirmation.to_dict(), plus growing_oscillation.
Return type:: dict[str, object]

SettleCriterion

How a settle run is judged settled; see solve_steady_state(). "auto" starts with the velocity criterion and switches to the mean-drift criterion when a sustained, non-decaying oscillation is detected; a convergence record always holds the criterion that actually judged the run ("velocity" or "mean_drift").

alias of Literal[‘velocity’, ‘mean_drift’, ‘auto’]

class SettleCurveCheck(rotor_speed, pitch, tolerances)[source]

Bases: object

A settled operating point compared with the user’s operating curve.

When a settle run is seeded from a rotor-performance curve, the controller – not the curve – decides where the turbine settles, and that settled point is what is linearized. Comparing the two surfaces a disagreement between the controller and the curve (a mistuned controller, a curve for a different model or a different air density, a settle that has not reached its steady state). A deviation outside tolerance is reported, never treated as a failure.

Parameters:

rotor_speed (QuantityCheck) – Settled rotor speed (rpm; trimmed holds the settled value) against the curve, with a relative tolerance.
pitch (QuantityCheck) – Settled collective blade pitch (deg) against the curve, with an absolute tolerance.
tolerances (TrimTolerances) – The tolerances applied (only rotor_speed_rel and pitch_deg are used).

rotor_speed: QuantityCheck

pitch: QuantityCheck

tolerances: TrimTolerances

property status: CheckStatus

Return "flag" if either quantity is outside tolerance.

Returns:: {“pass”, “flag”, “unavailable”} – "flag" when the rotor speed or pitch deviates beyond tolerance, "unavailable" when either could not be compared, else "pass".

property flagged_quantities: tuple[str, ...]: Return the names of the quantities outside tolerance.

class SettlePlatformDamping(surge=0.0, sway=0.0, heave=0.0, roll=0.0, pitch=0.0, yaw=0.0)[source]

Bases: object

Temporary linear platform damping that speeds up a floating settle run.

The damping is added to the diagonal of HydroDyn’s AddBLin matrix (first body) in the settle copy only, for the first stage of a two-stage settle (see solve_steady_state()); it is removed again before the undamped confirmation run and never reaches a linearization case.

Why the settled mean is unchanged: the added load is F = -B q_dot. At a static equilibrium the platform velocity q_dot is zero, so the force is zero and the equilibrium equations – rotor thrust against mooring, hydrostatic and gravity restoring loads – are exactly those of the undamped model: the fixed point does not move. Over a stationary periodic response the mean of B q_dot is B (q(t+T) - q(t)) / T = 0 as well. Quadratic drag (AddBQuad, Morison drag) also vanishes at zero velocity, and the settle runs in still water, so there is no wave mean-drift force to change. Only the transient – the slow, lightly damped surge/sway/yaw ringing – decays faster. Caveats the undamped confirmation stage exists for: a model with more than one equilibrium (e.g. a controller region boundary) may be steered to a different one, and an oscillation the damping suppresses may be self-excited, in which case the undamped model has no stable equilibrium and its oscillation reappears.

Parameters:

surge (float, optional) – Added linear damping for the translational DOFs, N/(m/s). Default 0.
sway (float, optional) – Added linear damping for the translational DOFs, N/(m/s). Default 0.
heave (float, optional) – Added linear damping for the translational DOFs, N/(m/s). Default 0.
roll (float, optional) – Added linear damping for the rotational DOFs, N m/(rad/s). Default 0.
pitch (float, optional) – Added linear damping for the rotational DOFs, N m/(rad/s). Default 0.
yaw (float, optional) – Added linear damping for the rotational DOFs, N m/(rad/s). Default 0.

Raises:

ValueError – If any value is negative or non-finite, or if all are zero.

System identification

System identification — state-space export and Kalman-ready matrices.

State space and reduced-order models

Clean linear-time-invariant state-space representation.

A StateSpace holds the validated A, B, C, D matrices of a continuous- or discrete-time system together with the state, input, and output names. The averaged matrices of an MBC transform are exported directly into this form, and a zero-order-hold discretization is provided for use in a digital twin.

class StateSpace(a, b=None, c=None, d=None, state_names=<factory>, input_names=<factory>, output_names=<factory>, dt=None, output_mbc_coordinates=<factory>)[source]

Bases: object

A linear time-invariant state-space system.

Parameters:

a (npt.NDArray[np.float64]) – State matrix, shape (n_states, n_states).
b (npt.NDArray[np.float64] or None) – Input, output, and feedthrough matrices, shapes (n_states, n_inputs), (n_outputs, n_states), (n_outputs, n_inputs); any may be None.
c (npt.NDArray[np.float64] or None) – Input, output, and feedthrough matrices, shapes (n_states, n_inputs), (n_outputs, n_states), (n_outputs, n_inputs); any may be None.
d (npt.NDArray[np.float64] or None) – Input, output, and feedthrough matrices, shapes (n_states, n_inputs), (n_outputs, n_states), (n_outputs, n_inputs); any may be None.
state_names (list[str]) – Names of the states, inputs, and outputs; each is either empty or matches the corresponding dimension.
input_names (list[str]) – Names of the states, inputs, and outputs; each is either empty or matches the corresponding dimension.
output_names (list[str]) – Names of the states, inputs, and outputs; each is either empty or matches the corresponding dimension.
dt (float or None) – Sample time; None for a continuous-time system, otherwise the discrete sample time in seconds.
output_mbc_coordinates (list[str]) – Multi-blade coordinate of each output ("collective"/"cosine"/ "sine" for a transformed blade-triplet output, else ""), aligned with output_names. Empty when unknown. Carried from an MBC transform so a load map can tell a transformed multi-blade output apart from a literal per-blade channel.

Raises:

ValueError – If the matrix shapes or name lengths are inconsistent.

a: npt.NDArray[np.float64]

b: npt.NDArray[np.float64] | None = None

c: npt.NDArray[np.float64] | None = None

d: npt.NDArray[np.float64] | None = None

state_names: list[str]

input_names: list[str]

output_names: list[str]

dt: float | None = None

output_mbc_coordinates: list[str]

property n_states: int: Return the number of states.

property n_inputs: int

Return the number of inputs (from B, else D, else 0).

A feedthrough-only system (B is None but D present) still has D.shape[1] inputs; the feedthrough columns define them.

property n_outputs: int

Return the number of outputs (from C, else D, else 0).

A feedthrough-only system (C is None but D present) still has D.shape[0] outputs; the feedthrough rows define them.

property is_discrete: bool: Return whether the system is discrete-time.

is_stable()[source]

Return whether the system is asymptotically stable.

Returns:: bool – For a continuous system, whether every eigenvalue of A has negative real part; for a discrete system, whether every eigenvalue lies strictly inside the unit circle.
Return type:: bool

discretized(dt)[source]

Return a zero-order-hold discretization at sample time dt.

Parameters:: dt (float) – Sample time in seconds; must be positive.
Returns:: StateSpace – The discrete-time system; C and D are unchanged.
Raises:: ValueError – If dt is not a positive, finite number, or the system is already discrete.
Return type:: StateSpace

state_space_from_mbc(result)[source]

Export the averaged MBC matrices as a continuous-time state-space system.

Parameters:: result (MBCResult) – An MBC transform result whose avg_a is present.
Returns:: StateSpace – The continuous-time system with state names from the result.
Raises:: ValueError – If result.avg_a is None.
Return type:: StateSpace

static_gain(system)[source]

Return the zero-frequency input-output gain D - C A^-1 B.

This quantity is especially important for module-level OpenFAST models: a very large direct stiffness can be cancelled by the equilibrium response of internal states. Preserving D alone during reduction then gives the wrong static physics even when the retained modes are otherwise accurate.

Raises:: ValueError – If the system is discrete, lacks B or C, or A is singular.
Parameters:: system (StateSpace)
Return type:: npt.NDArray[np.float64]

Real modal state-space realization from modal parameters.

A set of under-damped modes is realized as a real, block-diagonal state-space system. Each mode with eigenvalue \(\lambda = \sigma + j\omega\) contributes a 2x2 block

\[\begin{split}\begin{bmatrix} \sigma & -\omega \\ \omega & \sigma \end{bmatrix},\end{split}\]

whose eigenvalues are \(\sigma \pm j\omega\), acting on the real and imaginary parts of the modal coordinate. When mode shapes are supplied, the output matrix maps the modal states to physical responses via \([\,2\operatorname{Re}\phi, \,-2\operatorname{Im}\phi\,]\). The result is a compact reduced-order model of the identified modes.

modal_state_space(eigenvalues, mode_shapes=None, *, output_names=None)[source]

Build a real modal state-space realization.

Parameters:

eigenvalues (npt.NDArray[np.complex128]) – Modal eigenvalues, shape (n_modes,).
mode_shapes (npt.NDArray[np.complex128] or None, optional) – Complex mode shapes, shape (n_outputs, n_modes); when given, the output matrix maps modal states to physical responses.
output_names (list[str] or None, optional) – Names of the outputs (the rows of mode_shapes).

Returns:

StateSpace – A continuous-time system with 2 * n_modes states.

Raises:

ValueError – If mode_shapes column count does not match the number of eigenvalues.

Return type:

StateSpace

modal_state_space_from_solution(solution)[source]

Build a modal realization from a ModalSolution.

Parameters:: solution (ModalSolution) – The modal solution whose eigenvalues and mode shapes are realized.
Returns:: StateSpace – The real modal state-space system, with outputs named by the solution’s DOF descriptions when available.
Return type:: StateSpace

Reduced-order modal models from a linearized state space.

A full OpenFAST linearization carries hundreds of states, many of them fast, weakly observable, or numerically marginal aero/actuator modes that a downstream estimator neither needs nor can stabilise. This module reduces the system to the few structural modes that actually drive a quantity of interest, in a real, block-diagonal modal realization that preserves the inputs and outputs.

Each retained underdamped mode \(\lambda = \sigma + j\omega\) (with right eigenvector \(\mathbf v\) and left eigenvector \(\mathbf w\), \(\mathbf w^{\mathsf H}\mathbf v = 1\)) becomes a real \(2\times2\) block

\[\begin{split}\mathbf A_k = \begin{bmatrix}\sigma & -\omega\\ \omega & \sigma\end{bmatrix},\quad \mathbf B_k = \begin{bmatrix}\operatorname{Re}(\mathbf w^{\mathsf H}\mathbf B)\\ \operatorname{Im}(\mathbf w^{\mathsf H}\mathbf B)\end{bmatrix},\quad \mathbf C_k = \big[\,2\operatorname{Re}(\mathbf C\mathbf v)\ \; -2\operatorname{Im}(\mathbf C\mathbf v)\,\big],\end{split}\]

with the feed-through \(\mathbf D\) unchanged. The block’s eigenvalues are exactly \(\sigma\pm j\omega\), so the retained modal frequencies and damping are preserved to machine precision. Modes are ranked by their residue in a chosen output (the load-observability ranking): the residue of mode \(k\) in output \(i\) is \(|\mathbf C_i\mathbf v_k|\), i.e. how strongly that mode appears in that load.

This is the reduction engine the digital-twin / reduced-estimator path depends on. It is the modal counterpart to balanced truncation; unlike balanced truncation it tolerates the unstable aero poles a turbine linearization contains (they are simply not selected, and any retained pole can optionally be reflected into the stable half-plane).

class ModalReduction(system, frequencies_hz, damping_ratios, residues, energy_retained, n_full_states, n_stabilized, state_projection=None, state_reconstruction=None, stabilized=None)[source]

Bases: object

A modally reduced state space and the modes it retained.

Parameters:

system (StateSpace) – The reduced, real, block-diagonal continuous state space (two states per retained mode), with the original inputs and outputs.
frequencies_hz (npt.NDArray[np.float64]) – Natural frequency of each retained mode (Hz), in the reduced state order.
damping_ratios (npt.NDArray[np.float64]) – Damping ratio of each retained mode, consistent with the realized reduced A block: a mode reflected into the stable half-plane (see n_stabilized) reports its post-stabilisation (positive) damping, not the original value.
residues (npt.NDArray[np.float64]) – The ranking residue of each retained mode (its magnitude in the ranked output, or its observability norm when no output was specified).
energy_retained (float) – Fraction of the candidate modes’ total squared residue captured by the retained modes, in [0, 1] — a cheap measure of how much of the ranked output’s modal content the reduction keeps.
n_full_states (int) – Number of states in the original system.
n_stabilized (int) – How many retained modes had an unstable eigenvalue reflected into the stable half-plane (0 unless the system had unstable poles among those kept).
state_projection (npt.NDArray[np.float64] or None) – Real map from a full physical state into the retained modal coordinates.
state_reconstruction (npt.NDArray[np.float64] or None) – Real map from retained modal coordinates back to the selected full-state subspace. Together these maps permit a consistently based periodic/LPV projection without independently reducing and re-phasing every azimuth.
stabilized (npt.NDArray[np.bool] or None) – Per retained mode, True where an unstable eigenvalue was reflected into the stable half-plane (n_stabilized is its count). The physical (pre-reflection) damping of a reflected mode is -damping_ratios[k]; its natural frequency is unchanged. None for a hand-built reduction that does not record it.

system: StateSpace

frequencies_hz: npt.NDArray[np.float64]

damping_ratios: npt.NDArray[np.float64]

residues: npt.NDArray[np.float64]

energy_retained: float

n_full_states: int

n_stabilized: int

state_projection: npt.NDArray[np.float64] | None = None

state_reconstruction: npt.NDArray[np.float64] | None = None

stabilized: npt.NDArray[np.bool_] | None = None

modal_reduction(system, *, n_modes=None, frequency_band_hz=None, rank_output=None, rank_outputs=None, required_transfer_pairs=None, n_required_transfer_modes=0, stabilize=True, match_dc_gain=False)[source]

Reduce a state space to a real modal realization of its dominant modes.

Keeps the underdamped modes (optionally within a frequency band) with the largest residue, ranked in a chosen output (rank_output, the load-observability ranking) by an equal-weight, unit-normalized joint residue over several outputs (rank_outputs), or by the overall observability norm, as a real block-diagonal model with the inputs and outputs preserved. The retained modal frequencies and damping are exact; the full model’s many marginal/unstable aero modes are simply dropped.

Parameters:

system (StateSpace) – A continuous-time system (dt is None) with a C matrix.
n_modes (int or None, optional) – Number of modes to retain (the highest-residue ones). None keeps every candidate mode (every underdamped mode in the band).
frequency_band_hz (tuple[float, float] or None, optional) – Restrict candidates to modes whose natural frequency is in [low, high] (Hz), e.g. the structural band. None imposes no band.
rank_output (int or str or None, optional) – Rank modes by their residue in this output (index or name) — keep the modes that drive this load. None ranks by the observability norm over all outputs unless rank_outputs is given.
rank_outputs (Sequence[int or str] or None, optional) – Rank modes jointly for these output rows. Each row with numerically resolved candidate-mode content has its modal-residue vector normalized to unit Euclidean norm before the rows are combined, so quantities with different physical units (for example platform motion and line tension) receive equal weight. Mutually exclusive with rank_output.
required_transfer_pairs (sequence of tuple(output, input) or None, optional) – Input-output pairs whose strongest transfer-function modes must be retained before the remaining modal budget is allocated by the output ranking. Each pair is ranked by the true modal transfer residue \(|(C_i v_k)(w_k^H B_j)|\), normalized so pairs in different units receive equal weight. This is intended for reduced observers that must preserve a measured response to an estimated unknown input.
n_required_transfer_modes (int, optional) – Number of modes reserved for required_transfer_pairs. Must be zero when no pairs are supplied, positive when they are supplied, and no greater than n_modes when that budget is finite. Default 0.
stabilize (bool, optional) – Reflect any retained unstable eigenvalue into the stable half-plane (sigma -> -|sigma|), so the reduced model is a stable estimator basis. Default True.
match_dc_gain (bool, optional) – Correct the reduced feedthrough so its zero-frequency gain exactly matches the full model. This preserves equilibrium stiffness when a large direct term is cancelled by omitted internal-state response. Both models must have B and nonsingular A matrices. Default False.

Returns:

ModalReduction – The reduced system and the retained-mode metadata.

Raises:

ValueError – If the system is discrete, has no C matrix, n_modes is not positive, frequency_band_hz is invalid, the ranking selections conflict or are empty, no modes remain after filtering, or a retained mode belongs to a defective (non-diagonalizable) repeated-eigenvalue cluster — a Jordan chain a block-diagonal modal realization cannot represent.

Return type:

ModalReduction

Notes

The realization is exact for diagonalizable systems, including genuinely repeated (but non-defective) eigenvalues. A defective repeated mode (a Jordan chain) cannot be written as independent modal blocks and is rejected rather than silently reduced to a model with a different transfer function.

output_mode_residues(system, output)[source]

Rank the underdamped modes by their residue in one output (load).

The residue of mode \(k\) in the output is \(|\\mathbf C_i\\mathbf v_k|\) — how strongly the mode appears in that load. This is the load-observability ranking that drives modal_reduction() and is the basis for choosing which modes a load estimator must retain.

Parameters:

system (StateSpace) – A continuous system with a C matrix.
output (int or str) – The output row index, or an output name (exact match, else substring).

Returns:

tuple of npt.NDArray[np.float64] – (frequencies_hz, damping_ratios, residues) for the underdamped modes, sorted by descending residue.

Raises:

ValueError – If the system is discrete, has no C matrix, or the output cannot be resolved.

Return type:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64], npt.NDArray[np.float64]]

Balanced truncation — gramian-based reduction with an a-priori error bound.

modal_reduction() keeps whole modes chosen by their residue in a load. Balanced truncation is the complementary, input-output-optimal reduction: it balances the controllability and observability Gramians so that each state is equally hard to reach and to observe, then drops the states with the smallest Hankel singular values — the ones that contribute least to the transfer function. Unlike modal reduction it comes with a guarantee: the truncated model’s worst-case frequency-response error is bounded a priori by twice the sum of the discarded Hankel singular values.

For a stable system the Gramians solve the Lyapunov equations \(\mathbf A\mathbf W_c+\mathbf W_c\mathbf A^{\mathsf T}+\mathbf B\mathbf B^{\mathsf T}=\mathbf 0\) and \(\mathbf A^{\mathsf T}\mathbf W_o+\mathbf W_o\mathbf A+ \mathbf C^{\mathsf T}\mathbf C=\mathbf 0\) (discrete analogues for a sampled system). The Hankel singular values are \(\sigma_i=\sqrt{\lambda_i(\mathbf W_c\mathbf W_o)}\), and in the balanced realization both Gramians equal \(\operatorname{diag}(\sigma)\). This reduction requires asymptotic stability (the Gramians exist) and that every retained Hankel singular value be resolved above rounding level (the retained order is controllable and observable). The Gramians are factored from their symmetric eigendecomposition with rounding-level negative eigenvalues clipped, so the numerically indefinite Gramians of a lightly damped minimal system do not cause a spurious rejection. It suits the structural ROM, while the unstable aero poles of a raw turbine linearization are handled by modal_reduction() instead.

class BalancedReduction(system, hankel_singular_values, error_bound, n_full_states)[source]

Bases: object

A balanced-truncation reduction and its Hankel-singular-value spectrum.

Parameters:

system (StateSpace) – The reduced (or, when no order is given, balanced full-order) system, with the original inputs and outputs and the feed-through D unchanged.
hankel_singular_values (npt.NDArray[np.float64]) – All Hankel singular values of the full system, in descending order. The retained states correspond to the largest ones; the tail is what the error bound sums.
error_bound (float) – The a-priori worst-case frequency-response error 2 * sum(discarded Hankel singular values) — an upper bound on the \(\mathcal H_\infty\) error \(\lVert\mathbf G-\mathbf G_r\rVert_\infty\). Zero when nothing is dropped.
n_full_states (int) – Number of states in the original system.

system: StateSpace

hankel_singular_values: npt.NDArray[np.float64]

error_bound: float

n_full_states: int

balanced_truncation(system, *, n_states=None, tol=None)[source]

Reduce a system by balanced truncation, with an a-priori error bound.

Balances the controllability and observability Gramians, then keeps the states with the largest Hankel singular values. The order is set by n_states (an explicit count) or tol (drop singular values at or below tol times the largest); with neither, the system is balanced but not truncated.

Parameters:

system (StateSpace) – A stable system with both B and C matrices. May be continuous (dt is None) or discrete.
n_states (int or None, optional) – Number of states to retain (the largest Hankel singular values). Takes precedence over tol. Must be in [1, n_states_full].
tol (float or None, optional) – Relative threshold: retain the states whose Hankel singular value exceeds tol * max(sigma). Must be non-negative.

Returns:

BalancedReduction – The reduced system, the full Hankel-singular-value spectrum, and the bound.

Raises:

ValueError – If the system lacks B or C, is not asymptotically stable, the retained order includes a Hankel singular value at rounding level (the system is not minimal at that order), or n_states/tol is out of range.

Return type:

BalancedReduction

Operating-point ROM family with consistently-tracked modes (LPV packaging).

A turbine is linearized at many operating points (wind speed, rotor speed, …), and the digital twin wants one reduced model per point so it can schedule the estimator on the operating condition. Reducing each point independently is not enough: the reduction ranks modes by their residue, so the order — and the meaning of “mode 2” — changes from point to point as modes veer and cross. This module reduces every point and then tracks the modes across the family, so a given index is the same physical mode at every operating point: a proper linear-parameter-varying (LPV) packaging of the ROM.

Modes are matched between adjacent operating points by the Modal Assurance Criterion of their output residues (how each mode appears at the outputs — the same quantity the reduction ranks on), with a frequency-proximity tie-breaker, via an optimal (Hungarian) assignment. Each tracked mode carries the MAC value against the previous point, so a low value flags where the tracking is uncertain (a crossing or veering region) — the hook the operating-envelope-consistency analysis needs.

class RomFamily(operating_points, systems, frequencies_hz, damping_ratios, tracking_mac, stabilized=<factory>)[source]

Bases: object

A parameter-indexed family of reduced models with tracked modes.

Parameters:

operating_points (npt.NDArray[np.float64]) – The scheduling-parameter value of each point, shape (n_points,), in the order given.
systems (list[StateSpace]) – The reduced model at each operating point, all with the same mode (and state) ordering: index k is the same physical mode across the family.
frequencies_hz (npt.NDArray[np.float64]) – Natural frequency of each tracked mode, shape (n_points, n_modes).
damping_ratios (npt.NDArray[np.float64]) – Physical damping ratio of each tracked mode, shape (n_points, n_modes): the damping of the linearization’s own eigenvalue, negative for an unstable mode, even where the stored realization reflected that pole (see stabilized).
tracking_mac (npt.NDArray[np.float64]) – The MAC of each tracked mode against the previous operating point, shape (n_points, n_modes); the first row is all ones (the reference). A low value marks a mode whose tracking across that step is uncertain.
stabilized (npt.NDArray[np.bool], optional) – True where the stored realization in systems reflected that mode’s unstable pole into the stable half-plane, shape (n_points, n_modes). For such a mode the realized A block has damping -damping_ratios rather than the physical value. Defaults to all False (for hand-built families).

operating_points: npt.NDArray[np.float64]

systems: list[StateSpace]

frequencies_hz: npt.NDArray[np.float64]

damping_ratios: npt.NDArray[np.float64]

tracking_mac: npt.NDArray[np.float64]

stabilized: npt.NDArray[np.bool_]

build_rom_family(systems, operating_points, *, n_modes, frequency_band_hz=None, rank_output=None, rank_outputs=None, required_transfer_pairs=None, n_required_transfer_modes=0, frequency_weight=0.5, match_dc_gain=False, stabilize=True)[source]

Reduce a system at each operating point and track the modes across the family.

The reference point’s top-n_modes modes (by residue) define the tracked set. At each later point the system is reduced to all candidate modes and the tracked modes are matched against that full set by output-residue MAC (with a frequency tie-breaker), so a tracked mode is recovered even when it drops below the top-n_modes residue rank at that point; the matched modes are then selected and reordered to keep mode identity consistent.

Parameters:

systems (Sequence[StateSpace]) – One continuous-time linearization per operating point, with a C matrix and the same outputs throughout.
operating_points (Sequence[float]) – The scheduling-parameter value of each system (same length as systems).
n_modes (int) – Number of modes to retain and track at every point. Each point must yield at least this many underdamped modes.
frequency_band_hz (tuple[float, float] or None, optional) – Restrict the retained modes to this natural-frequency band (Hz).
rank_output (int or str or None, optional) – Rank modes by their residue in this output when reducing (see modal_reduction()).
rank_outputs (Sequence[int or str] or None, optional) – Rank modes by the equal-weight, unit-normalized joint residue of these outputs (see modal_reduction()). Mutually exclusive with rank_output.
required_transfer_pairs (sequence of tuple(output, input) or None, optional) – Observer input-output pairs whose strongest transfer-residue modes are reserved in the reference modal set (see modal_reduction()).
n_required_transfer_modes (int, optional) – Number of the n_modes slots reserved for those transfer pairs. The reserved set is fixed at the reference point and then tracked by mode identity (joint MAC/frequency matching over all candidates), not re-selected per point, so a reshuffled transfer ranking cannot swap physical modes; a reserved mode is only barred from matching a candidate with negligible transfer residue.
frequency_weight (float, optional) – Strength of the frequency-proximity tie-breaker in [0, 1] used when matching modes between points (default 0.5).
match_dc_gain (bool, optional) – After the tracked modal subset is selected, correct each reduced feedthrough so its zero-frequency gain exactly equals its corresponding full system. This is applied after truncation (not to the all-candidate intermediate model), thereby preserving equilibrium stiffness for the actual stored family. Default False.
stabilize (bool, optional) – Reflect a retained unstable pole into the stable half-plane in the stored realizations (see modal_reduction()), so each member is a stable estimator basis. Default True. The reported RomFamily.damping_ratios are always the physical (pre-reflection) values, RomFamily.stabilized marks every reflected mode, and a warning is logged when any mode was reflected. False stores the unstable poles.

Returns:

RomFamily – The reduced models in a consistent mode order, with per-point frequencies, physical damping ratios, the per-step tracking MAC, and the reflection mask.

Raises:

ValueError – If systems is empty, its length differs from operating_points, n_modes is not positive, the systems do not share the same output layout, input dimension, and time domain, operating_points are not finite and strictly monotonic, or a point yields fewer than n_modes modes.

Return type:

RomFamily

combine_rom_families(base, enrichment, *, duplicate_frequency_tolerance_hz=1e-08, enrichment_outputs=None)[source]

Compose two disjoint tracked modal families without re-reducing either.

The base and enrichment must use the same operating-point schedule and I/O layout. Their modal state blocks are concatenated, their output contributions are summed through a horizontal C concatenation, and the shared feedthrough is retained once. A frequency-separation check rejects a mode present in both families, which would otherwise double-count its transfer residue.

Parameters:

base (RomFamily) – Independently tracked, continuous- or discrete-time modal families with the same schedule, input/output names, MBC labels, feedthrough, and sample time.
enrichment (RomFamily) – Independently tracked, continuous- or discrete-time modal families with the same schedule, input/output names, MBC labels, feedthrough, and sample time.
duplicate_frequency_tolerance_hz (float, optional) – Maximum absolute per-point frequency difference considered a duplicate. Default 1e-8 Hz.
enrichment_outputs (sequence of int or str or None, optional) – Output rows to which the enrichment is allowed to contribute. None keeps every enrichment output. A declared subset zeros all other enrichment C rows while leaving the base family untouched; this supports separated observer blocks, such as drivetrain modes used only by a rotor-speed measurement.

Returns:

RomFamily – A block-composed family with base modes first and enrichment modes second.

Raises:

ValueError – If the tolerance is invalid, schedules or I/O layouts differ, feedthroughs do not match exactly, or a duplicate modal branch is detected.

Return type:

RomFamily

Physical-state LPV family export: named operating-point plants from .lin files.

build_rom_family() packages reduced, mode-tracked models for modal/Campbell work. This module is the complementary export for control design: it reads a directory of OpenFAST linearization files and assembles, per operating point, a state-space model whose states/inputs/outputs are the named physical DOFs the caller selects (e.g. "ED PtfmPitch", "GenTq", "BldPitch1"), with a consistent ordering across the operating-point sweep – the linear-parameter-varying plant a gain-scheduled controller schedules on.

The matrices are azimuth-averaged in the physical (rotating) frame, preserving the original per-blade channel names; no MBC/Coleman transform is applied (for the multi-blade coordinate representation use build_rom_family() / state_space_from_mbc()). The result is one LTI model per operating point – the standard plant for LQR/LPV control synthesis. This is the single VANE entry point a downstream controller needs: it never touches raw .lin files itself.

class LPVFamily(scheduling_points, systems, state_names=<factory>, input_names=<factory>, output_names=<factory>, scheduling_variable='WindSpeed', scheduling_unit='m/s', auto_added_states=<factory>, dropped_coupling_a=<factory>, dropped_coupling_c=<factory>)[source]

Bases: object

A parameter-indexed family of named physical-state plants for control design.

Parameters:

scheduling_points (npt.NDArray[np.float64]) – The scheduling-variable value of each operating point, shape (n_points,), sorted strictly ascending. In the raw linearization unit: WindSpeed in m/s, RotorSpeed in rad/s (not rpm).
systems (list[StateSpace]) – The physical-state plant at each operating point, in the same order as scheduling_points. Every system has the same selected states, inputs, and outputs, in the same order – the consistency a scheduled controller relies on.
state_names (list[str]) – The selected physical state, input, and output names, shared by every system.
input_names (list[str]) – The selected physical state, input, and output names, shared by every system.
output_names (list[str]) – The selected physical state, input, and output names, shared by every system.
scheduling_variable (str) – The scheduling variable the family is indexed on (e.g. "WindSpeed").
scheduling_unit (str) – The physical unit of scheduling_points in the raw linearization convention: "m/s" for WindSpeed, "rad/s" for RotorSpeed (not rpm, unlike the modal/Campbell path). Carried explicitly so a scheduled controller cannot mis-schedule by assuming the wrong unit.
auto_added_states (list[str]) – The states the builder added to the request to complete a position/velocity pair (see pair_derivatives in build_physical_lpv_family()), named by their unit-stripped linearization descriptions. Each also appears in state_names. Empty when nothing was added.
dropped_coupling_a (npt.NDArray[np.float64]) – Per operating point, the relative state-matrix coupling the state selection discards, ||A[s, ~s]||_F / ||A[s, :]||_F (s the selected states), shape (n_points,), in the order of scheduling_points. Zero when every state is selected.
dropped_coupling_c (npt.NDArray[np.float64]) – Per operating point, the relative output coupling the selection discards, ||C[o, ~s]||_F / ||C[o, :]||_F (o the selected outputs), shape (n_points,). Zero when no outputs are selected or every state is selected.

scheduling_points: npt.NDArray[np.float64]

systems: list[StateSpace]

state_names: list[str]

input_names: list[str]

output_names: list[str]

scheduling_variable: str = 'WindSpeed'

scheduling_unit: str = 'm/s'

auto_added_states: list[str]

dropped_coupling_a: npt.NDArray[np.float64]

dropped_coupling_c: npt.NDArray[np.float64]

property dropped_coupling: npt.NDArray[np.float64]

Per-point relative dropped coupling, the larger of the A and C terms.

Returns:: npt.NDArray[np.float64] – max(dropped_coupling_a, dropped_coupling_c) element-wise, shape (n_points,). This is the quantity max_dropped_coupling checks.

build_physical_lpv_family(lin_dir, *, states, inputs=(), outputs=(), scheduling_var='WindSpeed', pair_derivatives=True, max_dropped_coupling=0.05)[source]

Build a named physical-state LPV plant family from a directory of .lin files.

Discovers the operating points in lin_dir, averages each point’s azimuth files in the physical frame, and selects the named states/inputs/outputs into a state-space model – one per operating point, ordered by scheduling_var, with the same channel layout everywhere. No MBC transform is applied, so per-blade channel names are preserved (use build_rom_family() for the multi-blade coordinate representation).

Selecting a state subset truncates the plant: rows and columns of the unselected states are removed, discarding their coupling into the selected ones. Two safeguards keep that truncation honest. Second-order DOFs are completed with their position/velocity twin (pair_derivatives), and the relative coupling the selection still drops is measured at every point and checked (max_dropped_coupling).

Parameters:

lin_dir (str or pathlib.Path) – Directory of OpenFAST .lin files, searched recursively, so a campaign laid out with one sub-directory per operating point is read as distinct points (grouped into operating points by case name).
states (Sequence[str]) – Physical state names to select, e.g. ["ED PtfmPitch", "ED RotSpeed"]. Matched against the linearization’s state descriptions (units stripped): an exact match is preferred, else a unique substring. When a name matches both a DOF and its "First time derivative of <DOF>" twin, the position DOF is chosen (and, with pair_derivatives, its twin is then added); a name matching two genuinely different channels raises, listing them. The selected order is the state order, with any auto-added twin inserted next to its partner.
inputs (Sequence[str], optional) – Input and output names to select (e.g. ["GenTq", "BldPitch1"]); empty selects none (no B / C).
outputs (Sequence[str], optional) – Input and output names to select (e.g. ["GenTq", "BldPitch1"]); empty selects none (no B / C).
scheduling_var (str, optional) – The scheduling variable: "WindSpeed" (default, m/s) or "RotorSpeed". RotorSpeed is the raw linearization rotor speed in rad/s (the unit OpenFAST writes), not rpm — unlike the modal/Campbell path, which reports rotor speed in rpm. Schedule a controller built against rad/s accordingly.
pair_derivatives (bool, optional) – If true (default), every selected second-order DOF whose twin – the "First time derivative of <DOF>" velocity of a selected position, or the position of a selected velocity – exists in the linearization but was not requested gets that twin added, immediately after a position or immediately before a velocity, so each pair reads position then velocity. The added names (unit-stripped descriptions) are logged at INFO and recorded in LPVFamily.auto_added_states. A position without its velocity is a pure truncation artefact (d(position)/dt is exactly the dropped velocity), so disable this only to reproduce a deliberate truncation.
max_dropped_coupling (float or None, optional) – Ceiling on the relative coupling the state selection discards, default 0.05. At each operating point VANE computes ||A[s, ~s]||_F / ||A[s, :]||_F over the selected states s and, when outputs are selected, ||C[o, ~s]||_F / ||C[o, :]||_F over the selected outputs o; the per-point value is the larger of the two (LPVFamily.dropped_coupling). If the largest value over the family exceeds the ceiling, ValueError is raised naming the worst point and the dropped states contributing most. The norms are taken in the linearization’s own units, so the measure is a screening check, not a unit-invariant error bound. None disables the check (the norms are still recorded). Must be a finite number >= 0.

Returns:

LPVFamily – The physical-state plant family, with scheduling_points sorted ascending and a StateSpace per point sharing the selected channel layout. Its state_names is the final (paired) state list; auto_added_states, dropped_coupling_a and dropped_coupling_c record the pairing and the per-point truncation norms.

Raises:

FileNotFoundError – If lin_dir does not exist or contains no .lin files.
ValueError – If scheduling_var is unknown; max_dropped_coupling is not None or a finite number >= 0; a name selection is invalid (a bare string, an empty states, a duplicate, or a non-string entry); a requested name is missing/ambiguous; a name resolves to a different channel (or different units) across operating points; an operating point’s azimuth files disagree on the channel layout or the operating condition (wind or rotor speed) or contain a duplicate azimuth; the schedule is non-finite or not increasing; or the state selection drops more coupling than max_dropped_coupling allows.

Return type:

LPVFamily

Safe, provenance-stamped save/reload for estimator results and model families.

An estimator’s outputs are evidence: a filtered trajectory or a scheduled run must be reproducible and archivable, not recomputed from memory. This module serializes the vane.sysid result dataclasses, the tracked RomFamily and the physical-state LPVFamily to a single .npz file each and loads them back exactly.

The format is deliberately safe and transparent: the numeric arrays are stored as plain NumPy arrays and every other field as a JSON metadata blob, so a result is loaded with allow_pickle=False – it can carry no executable payload, unlike a pickle or joblib artifact. Each file also records the result type and the VANE version that produced it, so an archived result is traceable to the code that made it.

LPV_FAMILY_SCHEMA_VERSION = 1: Schema version of the LPV-family archive written by save_lpv_family(). load_lpv_family() reads only this version and names both versions when an archive records another one.

load_lpv_family(path)[source]

Load a physical-state LPV family saved by save_lpv_family().

The archive is opened with allow_pickle=False. Its format tag and schema version are checked first, then every array and metadata field, and the rebuilt family is validated as on saving, so a file that loads is a family that save_lpv_family() could have written. The arrays, names, scheduling variable and unit, auto-added states and dropped-coupling norms come back exactly as saved.

Parameters:: path (str or os.PathLike) – The .npz file written by save_lpv_family() (the suffix is added if absent).
Returns:: vane.sysid.physical_lpv.LPVFamily – The reconstructed family.
Raises:: ValueError – If the file is not a VANE LPV-family archive, records no schema version or a schema other than LPV_FAMILY_SCHEMA_VERSION (the message names both versions and the VANE version that wrote the file), or is incomplete, has unexpected entries or holds an invalid family.
Return type:: LPVFamily

load_result(path)[source]

Load an estimator result saved by save_result().

Reads the archive with allow_pickle=False (so a tampered file can carry no executable payload), reconstructs the recorded result type, and returns it exactly as saved – arrays, names, flags, and the nested consistency report.

Parameters:: path (str or os.PathLike) – The .npz file written by save_result().
Returns:: FilterResult or ScheduledFilterResult – The reconstructed result.
Raises:: ValueError – If the file is not a VANE estimator-result archive or records an unknown type.
Return type:: FilterResult | ScheduledFilterResult

load_rom_family(path)[source]

Load a RomFamily written by save_rom_family() safely.

An archive without the RomFamily.stabilized mask loads with an all-False one.

Parameters:: path (str | PathLike[str])
Return type:: RomFamily

save_lpv_family(family, path)[source]

Save a physical-state LPVFamily to .npz.

The archive holds the scheduling points, the per-point dropped-coupling norms and each system’s matrices as plain arrays under explicit indexed keys, and every other field (channel names, the scheduling variable and its unit, the auto-added states, each system’s names, sample time and matrix presence) as JSON metadata. It is stamped with the format tag, LPV_FAMILY_SCHEMA_VERSION and the producing VANE version. No object arrays are used, so load_lpv_family() opens it with allow_pickle=False.

Parameters:

family (vane.sysid.physical_lpv.LPVFamily) – The family, e.g. from vane.export.build_physical_lpv_family().
path (str or os.PathLike) – Destination file (a .npz is written; the suffix is added if absent).

Raises:

TypeError – If family is not exactly an LPVFamily, a system is not exactly a StateSpace, or a field has the wrong type.
ValueError – If the family is empty, its arrays are non-finite or of the wrong length, the scheduling points are not strictly ascending, or the systems do not share one layout (matrix shapes, names and sample time).

Return type:

None

save_result(result, path)[source]

Save an estimator result to a .npz file.

Writes the result’s NumPy arrays as plain arrays and the remaining fields (names, flags, the nested consistency report) as a JSON metadata blob, stamped with the result type and the producing VANE version. The file is self-describing and loads back with load_result() without executing any embedded code.

Parameters:

result (FilterResult or ScheduledFilterResult) – The estimator result to serialize.
path (str or os.PathLike) – Destination file (a .npz is written; the suffix is added if absent).

Raises:

TypeError – If result is not a registered estimator-result type, or carries a field that cannot be serialized.

Return type:

None

save_rom_family(family, path)[source]

Save a tracked RomFamily as a transparent pickle-free archive.

Each state-space matrix is stored under an explicit indexed key; names, sample times, and optional-matrix presence are JSON metadata. No object arrays are used, so load_rom_family() always opens the archive with allow_pickle=False. The per-mode reflection mask RomFamily.stabilized is stored alongside the modal metadata.

Parameters:

family (RomFamily)
path (str | PathLike[str])

Return type:

None

Periodic systems

Rotor-azimuth-periodic ROMs in one fixed modal coordinate system.

Reducing every azimuth independently produces arbitrarily re-phased modal states that cannot be scheduled safely. This module instead takes one accepted averaged modal reduction and projects every retained per-azimuth MBC Jacobian through that same left/ right basis. The resulting matrices form a linear time-periodic (LTP) family whose state has a consistent meaning around the full revolution.

class PeriodicStateSpace(azimuths_deg, systems)[source]

Bases: object

A full-revolution matrix family in a fixed reduced-state basis.

Parameters:

azimuths_deg (npt.NDArray[np.float64])
systems (tuple[StateSpace, ...])

azimuths_deg: npt.NDArray[np.float64]

systems: tuple[StateSpace, ...]

at(azimuth_deg)[source]

Linearly interpolate the periodic family, including the 360/0 seam.

Parameters:: azimuth_deg (float)
Return type:: StateSpace

discretized(dt)[source]

Exactly discretize every tabulated member before online interpolation.

Parameters:: dt (float)
Return type:: PeriodicStateSpace

periodic_state_space_from_mbc(result, reduction)[source]

Project retained per-azimuth MBC matrices through one modal basis.

The averaged reduced A is retained as the stable reference and projected per-azimuth deviations are added to it. Thus any intentionally reflected unstable poles remain reflected while the measured cyclic Jacobian variation is preserved.

The B/C/D deviations are mapped onto the reduction’s channels by input name and by output name plus MBC coordinate, so a reduction whose outputs or inputs are a reordering of the MBC result’s is remapped rather than corrupted. When either side is unnamed the channels are matched by position and only the counts are checked.

Parameters:

result (MBCResult) – An MBC result built with per-azimuth matrices retained.
reduction (ModalReduction) – A modal reduction of the result’s averaged system, with its projection maps.

Returns:

PeriodicStateSpace – One reduced member per azimuth in the reduction’s fixed basis and channel order.

Raises:

ValueError – If required averaged or per-azimuth matrices are missing, dimensions disagree, or the reduction’s input/output layout is not a permutation of the MBC result’s input/output descriptions (and output MBC coordinates).

Return type:

PeriodicStateSpace

Loads and frequency response

Quantity-of-interest (load) map from a linearized output equation.

A linearization’s output equation \(y = C x + D u\) already contains the sensitivity of every requested output — including structural loads such as mooring fairlead/anchor tensions, tower-base and yaw-bearing moments, and blade-root moments — to the system state and inputs. This module turns that into an explicit, auditable quantity-of-interest (QoI) map: for each load output it exposes

the state sensitivity (its row of \(C\)): how each state moves the load;
the input sensitivity (its row of \(D\)): the direct feed-through from the inputs (wind, wave, control) to the load, bypassing the dynamics; and
the modal residues \(C_i \Phi\): how each identified mode contributes to the load. Writing the state in modal coordinates \(x = \Phi q\) gives \(y_i = (C_i \Phi)\, q\), so the residue of mode \(k\) is the complex gain with which that mode appears in load \(i\). This is the bridge from a modal identification to load monitoring: it answers which modes drive this load.

The modal residues are taken over the retained (under-damped) modes of a ModalSolution; over-damped/rigid-body modes and the direct \(D u\) feed-through are not part of that modal sum and are reported separately (the input sensitivity). The map is a static, deterministic property of the linear model — the reduced-order foundation a downstream estimator consumes.

class QoiMap(sensitivities, state_names, input_names, mode_frequencies_hz=None)[source]

Bases: object

A map of output channels to their state/input/modal sensitivities.

Parameters:

sensitivities (list[QoiSensitivity]) – One entry per included output channel.
state_names (list[str]) – State descriptions indexing state_sensitivity.
input_names (list[str]) – Input descriptions indexing input_sensitivity.
mode_frequencies_hz (npt.NDArray[np.float64] or None) – Natural frequencies of the modes indexing modal_residues, or None when no modal solution was supplied.

sensitivities: list[QoiSensitivity]

state_names: list[str]

input_names: list[str]

mode_frequencies_hz: npt.NDArray[np.float64] | None = None

loads()[source]

Return only the structural-load sensitivities.

Return type:: list[QoiSensitivity]

by_category(category)[source]

Return the sensitivities of a given output category.

Parameters:: category (OutputCategory)
Return type:: list[QoiSensitivity]

get(name)[source]

Return the sensitivity whose channel name equals name.

Raises:: KeyError – If no channel has that exact name.
Parameters:: name (str)
Return type:: QoiSensitivity

modal_participation_table()[source]

Return a long-format table of modal contributions to each load.

Each row is one (load, mode) pair with the residue magnitude and phase and the per-load normalized magnitude (the fraction relative to that load’s strongest mode). Empty when no modal residues are available.

Returns:: pandas.DataFrame – Columns load, category, unit, mode, frequency_hz, residue_magnitude, residue_phase_deg, normalized.
Return type:: pd.DataFrame

class QoiSensitivity(name, info, output_index, state_sensitivity, input_sensitivity, modal_residues, mbc_coordinate='')[source]

Bases: object

Sensitivity of one output channel to the states, inputs, and modes.

Parameters:

name (str) – The output channel description.
info (OutputInfo) – Its classification (category, load flag, component, unit, …).
output_index (int) – Row index of this channel in C/D.
state_sensitivity (npt.NDArray[np.float64]) – The channel’s row of C, shape (n_states,): the linear sensitivity of the output to each state.
input_sensitivity (npt.NDArray[np.float64] or None) – The channel’s row of D, shape (n_inputs,), or None when the system has no feed-through matrix. The direct input-to-output gain.
modal_residues (npt.NDArray[np.complex128] or None) – The complex modal residues \(C_i \Phi\), shape (n_modes,), or None when no modal solution was supplied. The contribution of each retained mode to this output.
mbc_coordinate (str) – The multi-blade coordinate of the channel ("collective", "cosine", or "sine") when it is a transformed blade-triplet output, else "". A non-empty value means this row is a multi-blade combination rather than the literal per-blade channel its name suggests, so info.component is cleared to None.

name: str

info: OutputInfo

output_index: int

state_sensitivity: npt.NDArray[np.float64]

input_sensitivity: npt.NDArray[np.float64] | None

modal_residues: npt.NDArray[np.complex128] | None

mbc_coordinate: str = ''

property is_load: bool: Return whether this output is a structural load.

dominant_modes(top_n=3)[source]

Return the indices of the modes that contribute most to this output.

Parameters:: top_n (int) – Number of leading modes to return.
Returns:: npt.NDArray[np.int_] – Mode indices ordered by descending residue magnitude (empty when no modal residues are available).
Return type:: npt.NDArray[np.int_]

build_qoi_map(system, solution=None, *, output_mbc_coordinates=None, loads_only=True)[source]

Build the quantity-of-interest map from a state-space system.

Note

This is a modal-residue screening map — which modes drive which load channels in the linearized model — not a validated load ranking. The residues are in the linearization’s output units (and an MBC-averaged frame for rotating loads); they are not fatigue/DEL, design-load, or extreme-load magnitudes and must not be used as a substitute for a load-analysis or assessment calculation. Use it to decide which modes a downstream estimator should retain, then validate the estimator against time-domain or measured loads.

Parameters:

system (StateSpace) – A system carrying an output matrix C and named outputs. The optional feed-through D supplies the input sensitivities.
solution (ModalSolution or None, optional) – A modal solution of the same system; when given, the modal residues \(C_i \Phi\) are computed from its full eigenvectors so each load’s modal composition is available.
output_mbc_coordinates (list[str] or None, optional) – The multi-blade coordinate of each output, aligned with the system outputs. When None (the default) the system’s own output_mbc_coordinates are used, which state_space_from_mbc() populates — so an MBC-transformed system is handled correctly without any extra argument. A rotating blade-load output is a collective/cyclic combination, so when a channel’s coordinate is multi-blade its per-blade component index is cleared and the coordinate is recorded on the sensitivity. Pass an explicit list to override. Non-rotating loads (mooring, tower, platform) are unaffected.
loads_only (bool, optional) – When True (the default) include only channels classified as structural loads; when False include every output channel.

Returns:

QoiMap – The per-output sensitivities.

Raises:

ValueError – If the system has no C matrix or no output names, the output-name count disagrees with C, output_mbc_coordinates has the wrong length, or the modal solution’s eigenvectors do not span the system states.

Return type:

QoiMap

qoi_map_from_mbc(result, solution=None, *, loads_only=True)[source]

Build a QoI map directly from an MBC transform result.

A thin convenience over build_qoi_map(state_space_from_mbc(result), ...). The exported state-space carries the output multi-blade coordinates, so a rotating blade-load output is correctly identified as a multi-blade coordinate rather than mislabeled as a literal per-blade channel.

Parameters:

result (MBCResult) – An MBC transform result with an averaged output matrix.
solution (ModalSolution or None, optional) – A modal solution of the same averaged system, for the modal residues.
loads_only (bool, optional) – Restrict to structural-load channels (the default).

Returns:

QoiMap – The per-output sensitivities, with transformed blade outputs tagged by their multi-blade coordinate.

Return type:

QoiMap

Frequency-domain transfer and stochastic input-to-QoI propagation.

For a linear state-space model, the complex transfer matrix is

\[H(f) = C\left(sI-A\right)^{-1}B + D,\]

with \(s=j2\pi f\) for a continuous model and \(s=\exp(j2\pi f\Delta t)\) for a discrete model. If the input cross-spectral density is \(S_u(f)\), the model-implied output spectrum is

\[S_y(f) = H(f)S_u(f)H(f)^{\mathsf H}.\]

This is the auditable bridge between an input-estimation error spectrum and the motion/load quantities affected by that error. It does not consult output truth and does not claim nonlinear or out-of-support validity; those remain validation tasks.

class CrossSpectralDensity(frequencies_hz, density, channel_names)[source]

Bases: object

Named one-sided cross-spectral-density matrix.

density has shape (n_frequencies, n_channels, n_channels) and follows the covariance convention S[i, j] = E[X_i conj(X_j)].

Parameters:

frequencies_hz (npt.NDArray[np.float64])
density (npt.NDArray[np.complex128])
channel_names (tuple[str, ...])

frequencies_hz: npt.NDArray[np.float64]

density: npt.NDArray[np.complex128]

channel_names: tuple[str, ...]

class FrequencyResponse(frequencies_hz, response, input_names, output_names)[source]

Bases: object

Named complex input-to-output response on a frequency grid.

response has shape (n_frequencies, n_outputs, n_inputs).

Parameters:

frequencies_hz (npt.NDArray[np.float64])
response (npt.NDArray[np.complex128])
input_names (tuple[str, ...])
output_names (tuple[str, ...])

frequencies_hz: npt.NDArray[np.float64]

response: npt.NDArray[np.complex128]

input_names: tuple[str, ...]

output_names: tuple[str, ...]

frequency_response(system, frequencies_hz, *, input_channels=None, output_channels=None)[source]

Evaluate selected complex state-space transfers.

Parameters:

system (StateSpace) – Continuous or discrete state-space model with B and C matrices.
frequencies_hz (npt.ArrayLike) – Strictly increasing nonnegative physical frequencies in Hz. A discrete model is restricted to its Nyquist interval.
input_channels (Sequence[int | str] | None) – Optional unique indices or unambiguous names. By default all channels are retained.
output_channels (Sequence[int | str] | None) – Optional unique indices or unambiguous names. By default all channels are retained.

Return type:

FrequencyResponse

integrated_spectral_variance(spectrum, *, band_hz=None)[source]

Integrate each autospectrum over a declared frequency band.

Returns one nonnegative variance per channel. The trapezoidal integral runs exactly from band_hz[0] to band_hz[1]: the autospectra are linearly interpolated at band limits that fall between spectrum bins, so a band edge is not truncated to the nearest interior bin. The band is clipped to the spectrum’s frequency range, because the density is undefined outside it, and the clipped band must retain a positive width; this avoids silently reporting a zero-width integral. Without band_hz the whole spectrum grid is integrated.

Parameters:

spectrum (CrossSpectralDensity)
band_hz (tuple[float, float] | None)

Return type:

npt.NDArray[np.float64]

propagate_cross_spectral_density(response, spectrum)[source]

Propagate S_u through H as S_y = H S_u H^H.

Parameters:

response (FrequencyResponse)
spectrum (CrossSpectralDensity)

Return type:

CrossSpectralDensity

welch_cross_spectral_density(signals, *, sample_interval_s, segment_samples=None, overlap_samples=None, channel_names=None)[source]

Estimate a one-sided cross-spectral-density matrix using Welch averaging.

Samples are rows and channels are columns. A one-dimensional input is treated as one channel. Cross terms are retained, so correlated torque/thrust errors are propagated without the independence assumption.

Parameters:

signals (npt.ArrayLike)
sample_interval_s (float)
segment_samples (int | None)
overlap_samples (int | None)
channel_names (Sequence[str] | None)

Return type:

CrossSpectralDensity

Estimation

Ready-to-use Kalman-filter model assembly.

A KalmanModel bundles a state-space system with its process, measurement, and initial covariances into the exact matrices a Kalman filter consumes. The system can be discretized at a chosen sample time during assembly, and the covariance dimensions are validated against the system so the resulting model is internally consistent.

class KalmanModel(a, b, c, d, q, r, p0, dt=None, state_names=<factory>, output_names=<factory>)[source]

Bases: object

A state-space system with Kalman covariances, ready for filtering.

Parameters:

a (npt.NDArray[np.float64]) – State matrix, shape (n_states, n_states).
b (npt.NDArray[np.float64] or None) – Input, output, and feedthrough matrices.
c (npt.NDArray[np.float64] or None) – Input, output, and feedthrough matrices.
d (npt.NDArray[np.float64] or None) – Input, output, and feedthrough matrices.
q (npt.NDArray[np.float64]) – Process-noise, measurement-noise, and initial state covariances.
r (npt.NDArray[np.float64]) – Process-noise, measurement-noise, and initial state covariances.
p0 (npt.NDArray[np.float64]) – Process-noise, measurement-noise, and initial state covariances.
dt (float or None) – Sample time; None for a continuous-time model.
state_names (list[str]) – State and output names carried from the source system.
output_names (list[str]) – State and output names carried from the source system.

a: npt.NDArray[np.float64]

b: npt.NDArray[np.float64] | None

c: npt.NDArray[np.float64] | None

d: npt.NDArray[np.float64] | None

q: npt.NDArray[np.float64]

r: npt.NDArray[np.float64]

p0: npt.NDArray[np.float64]

dt: float | None = None

state_names: list[str]

output_names: list[str]

build_kalman_model(state_space, covariances, *, dt=None)[source]

Assemble a Kalman model from a state-space system and covariances.

Parameters:

state_space (StateSpace) – The continuous- or discrete-time system.
covariances (CovarianceSet) – The process, measurement, and initial covariances. Q is used exactly as given and must already be the discrete per-step covariance Q_d for the model’s sample time.
dt (float or None, optional) – When given and the system is continuous, discretize A/B at this sample time before assembly. Q is not discretized: convert a continuous-time Q_c (e.g. from vane.sysid.modal_process_noise()) with vane.sysid.discretize_process_noise() at the same dt first.

Returns:

KalmanModel – The assembled, dimension-checked model.

Raises:

ValueError – If dt is given for an already-discrete system, the covariance dimensions do not match the system, or a covariance is not a valid covariance matrix (Q/P0 must be finite, symmetric, and positive semidefinite; R must be finite, symmetric, and positive definite).

Return type:

KalmanModel

Runnable, auditable Kalman estimator over a KalmanModel.

The rest of vane.sysid builds and confirms an estimator-ready model; this module runs it. Given the discrete model and its covariances, KalmanFilter performs the recursive predict/update, with the properties a load-estimation digital twin needs to be trusted in the field:

Numerically stable – the gain is formed by a Cholesky solve (never an explicit inverse) and the covariance by the Joseph form, so the error covariance stays symmetric positive-semidefinite even for ill-conditioned innovations.
Tolerant of real measurement streams – each step accepts an available mask, so a dropped or missing sensor updates on the channels that reported; an optional NIS gate rejects outliers (a measurement whose normalized innovation squared exceeds a chi-square threshold) and the step is flagged rather than corrupting the estimate.
Zero-order-hold control timing – consistent with discretized(), the prediction into step k uses the previous sample’s control and the control logged with the measurement enters only the feedthrough: \(x_k = A x_{k-1} + B u_{k-1}\), \(y_k = C x_k + D u_k\).
Self-diagnosing – every step records the innovation and its normalized innovation squared (NIS); filter_consistency() checks the NIS sequence against its chi-square expectation so a mis-tuned Q/R is visible, not silent.
Auditable offline – rts_smoother() refines a recorded run with the Rauch-Tung-Striebel backward pass, and reconstruct_load() reads a linear load functional off the filtered state with its propagated standard deviation.

SteadyStateKalmanFilter runs the same recursion with the constant steady-state gain (from steady_state_estimator()), trading per-step Riccati updates for a fixed-gain filter once the covariance has converged.

class ConsistencyReport(mean_nis, expected_nis, lower, upper, consistent, n_accepted, n_gated=0)[source]

Bases: object

Whether a run’s innovations are statistically consistent with the model.

Parameters:

mean_nis (float) – Average normalized innovation squared over the tested steps – every step with a finite NIS, including steps the outlier gate rejected (their NIS is computed before the gate decision).
expected_nis (float) – The expected mean NIS under a correctly tuned filter – the average number of measurement channels per tested step (dof / (n_accepted + n_gated)).
lower (float) – The two-sided chi-square acceptance bounds for mean_nis at the chosen level.
upper (float) – The two-sided chi-square acceptance bounds for mean_nis at the chosen level.
consistent (bool) – Whether mean_nis lies within [lower, upper]; False flags a mis-tuned Q/R (over- or under-confident filter) or a record with more outliers than the model’s noise explains.
n_accepted (int) – Number of accepted (applied) steps included in the statistic.
n_gated (int, optional) – Number of gated-out (rejected) steps included in the statistic (default 0).

mean_nis: float

expected_nis: float

lower: float

upper: float

consistent: bool

n_accepted: int

n_gated: int = 0

class FilterResult(states, covariances, predicted_states, predicted_covariances, nis, accepted, n_active, state_names=<factory>)[source]

Bases: object

The recorded trajectory of a Kalman run, for diagnostics and smoothing.

Parameters:

states (npt.NDArray[np.float64]) – Filtered (a-posteriori) state means, shape (n_steps, n_states).
covariances (npt.NDArray[np.float64]) – Filtered error covariances, shape (n_steps, n_states, n_states).
predicted_states (npt.NDArray[np.float64]) – A-priori (predicted) state means before each update, same shape as states; retained so the RTS smoother can run without re-filtering.
predicted_covariances (npt.NDArray[np.float64]) – A-priori error covariances, shape (n_steps, n_states, n_states).
nis (npt.NDArray[np.float64]) – Normalized innovation squared at each step (nan where no measurement was available; a step rejected by the NIS gate keeps its finite value).
accepted (npt.NDArray[np.bool]) – Whether each step’s measurement was applied (False when fully masked or rejected by the NIS gate).
n_active (npt.NDArray[np.int]) – Number of measurement channels in each step’s innovation (its NIS degrees of freedom), recorded for a gated-out step too; 0 only where no channel was available. Equals n_outputs unless a partial available mask reduced it.
state_names (list[str]) – Names of the states, aligned with the last axis of states.

states: npt.NDArray[np.float64]

covariances: npt.NDArray[np.float64]

predicted_states: npt.NDArray[np.float64]

predicted_covariances: npt.NDArray[np.float64]

nis: npt.NDArray[np.float64]

accepted: npt.NDArray[np.bool_]

n_active: npt.NDArray[np.int_]

state_names: list[str]

class KalmanFilter(model, *, initial_state=None, initial_control=None)[source]

Bases: object

A recursive discrete Kalman filter over a KalmanModel.

Holds the current state estimate x and error covariance P and advances them with predict() and update() (or step() for both). The model must be discrete (dt set) and carry a C matrix.

Control timing (zero-order hold). The discrete model produced by discretized() holds each input constant over the sample interval that follows it, so the sampled plant is

\[\mathbf x_k = \mathbf A\mathbf x_{k-1} + \mathbf B\mathbf u_{k-1} + \mathbf w_{k-1}, \qquad \mathbf y_k = \mathbf C\mathbf x_k + \mathbf D\mathbf u_k + \mathbf v_k,\]

with u_k the input logged alongside the measurement y_k. step() therefore predicts with the previous sample’s control and uses the current one only in the feedthrough D u_k. The initial (x0, P0) is the prior one step before the first measurement; the control driving that first prediction is initial_control when given, and otherwise the first control passed to step() (the input is taken as held at its first logged value before the record, so a constant input is filtered exactly).

Parameters:

model (KalmanModel) – The discrete model and its Q, R, P0 covariances.
initial_state (npt.NDArray[np.float64] or None, optional) – Initial state mean x0 (the prior one step before the first measurement); defaults to zeros.
initial_control (npt.NDArray[np.float64] or None, optional) – The input u_{-1} held over the interval before the first measurement, which drives the first step()’s prediction. None (default) uses the first control passed to step() (pass zeros for a plant at rest before the record).

Raises:

ValueError – If the model is continuous (no dt), has no C matrix, initial_state does not match the state dimension, or initial_control is mis-sized, non-finite, or given for a model with neither B nor D.

x: npt.NDArray[np.float64]

predict(control=None)[source]

Advance one step with the control held over this interval.

\(x \leftarrow A x (+ B u)\), \(P \leftarrow A P A^{\mathsf T} + Q\).

This is the raw transition: control is the input held (zero-order hold) over the interval being predicted – for the interval ending at measurement k that is the previous sample’s input u_{k-1}, not u_k. step() and run_filter() apply this timing automatically.

Parameters:: control (npt.NDArray[np.float64] or None, optional) – The held input; None for no input over the interval.
Raises:: ValueError – If control is mis-sized, non-finite, or given for a model with neither B nor D.
Return type:: None

update(measurement, *, control=None, available=None, gate=None, gate_probability=None)[source]

Correct the state with a measurement; return its NIS, acceptance, and dof.

The predicted measurement is \(C x (+ D u_k)\), where u_k is the control logged with this measurement (not the one that drove the prediction), so a model with a nonzero feedthrough D requires it. Uses only the available output channels (a dropped sensor is simply omitted), a Cholesky solve for the gain, and the Joseph-form covariance update. With a gate set, a measurement whose normalized innovation squared exceeds the threshold is rejected (the state is left at its prediction) and reported as not accepted.

Parameters:

measurement (npt.NDArray[np.float64]) – The measured outputs, length n_outputs; entries at masked-out channels are ignored.
control (npt.NDArray[np.float64] or None, optional) – The control input logged with this measurement, used to subtract the feedthrough D u from the predicted measurement. Required (with a nonzero D matrix) for a correct innovation; ignored if the model has no D.
available (npt.NDArray[np.bool] or None, optional) – Boolean mask of reporting channels (length n_outputs); None uses every channel.
gate (float or None, optional) – A fixed chi-square NIS threshold for outlier rejection, applied as is whatever the number of reporting channels. Prefer gate_probability when channels can drop out.
gate_probability (float or None, optional) – Outlier-gate acceptance probability p in (0, 1): the threshold is chi2.ppf(p, n_used) for the n_used channels that reported, so a correctly tuned filter rejects a fraction 1 - p of steps regardless of dropout. Mutually exclusive with gate; neither applies every update.

Returns:

tuple[float, bool, int] – The normalized innovation squared (nan if no channel was available), whether the update was applied, and the number of channels in the innovation – the NIS degrees of freedom, reported for a gated-out step too; 0 only when no channel was available.

Raises:

ValueError – If both gates are given, gate is not a positive finite threshold, gate_probability is not in (0, 1), measurement is not length n_outputs or has non-finite available channels, or (with a nonzero D) control is missing, mis-sized, or non-finite.

Return type:

tuple[float, bool, int]

step(measurement, control=None, *, available=None, gate=None, gate_probability=None)[source]

Predict then update; return the update’s NIS, acceptance, and dof.

control is the input u_k logged with measurement. Under the zero-order-hold convention (see the class docstring) the prediction is driven by the previous step’s control u_{k-1} (on the first step, initial_control or else u_k itself), and u_k enters only the feedthrough D u_k; it is then held for the next step’s prediction.

Parameters:

measurement (npt.NDArray[np.float64]) – The measured outputs at this step.
control (npt.NDArray[np.float64] or None, optional) – The input logged with this measurement; None for no input.
available (optional) – As for update().
gate (optional) – As for update().
gate_probability (optional) – As for update().

Returns:

tuple[float, bool, int] – As for update().

Return type:

tuple[float, bool, int]

class SteadyStateKalmanFilter(a, c, gain, *, b=None, d=None, initial_state=None, state_names=None, initial_control=None)[source]

Bases: object

A constant-gain Kalman filter using the precomputed steady-state gain.

Once the error covariance has converged (the steady-state DARE solution from steady_state_estimator()), the gain is constant, so each step is a matrix-vector predict/correct with no per-step Riccati update – cheaper and ideal for an embedded twin. The covariance is fixed at the steady-state value.

It follows the same zero-order-hold control timing as KalmanFilter: the prediction into step k uses the previous step’s control u_{k-1} (on the first step, initial_control or else that step’s own control), and the control logged with the measurement enters only the feedthrough D u_k.

Parameters:

a (npt.NDArray[np.float64]) – Discrete state matrix.
c (npt.NDArray[np.float64]) – Output matrix.
gain (npt.NDArray[np.float64]) – The steady-state Kalman gain K (EstimatorAssessment.gain).
b (npt.NDArray[np.float64] or None, optional) – Input matrix, for control inputs into the state.
d (npt.NDArray[np.float64] or None, optional) – Feedthrough matrix; when given, D u is subtracted from the measurement so a controlled model with y = C x + D u is filtered correctly.
initial_state (npt.NDArray[np.float64] or None, optional) – Initial state mean (the prior one step before the first measurement); defaults to zeros.
state_names (list[str] or None, optional) – Names of the states.
initial_control (npt.NDArray[np.float64] or None, optional) – The input held over the interval before the first measurement (drives the first prediction); None (default) uses the first step’s own control.

Raises:

ValueError – If the gain shape is inconsistent with a/c, initial_state does not match the state dimension, or initial_control is mis-sized, non-finite, or given for a model with neither b nor d.

x: npt.NDArray[np.float64]

step(measurement, control=None)[source]

Predict then correct with the constant gain; return the new state estimate.

\(x^- = A x (+ B u_{k-1})\), then \(x = x^- + K (z - C x^- (- D u_k))\), with u_k = control the input logged with measurement and u_{k-1} the previous step’s control (the zero-order-hold timing of KalmanFilter).

Parameters:

measurement (npt.NDArray[np.float64])
control (npt.NDArray[np.float64] | None)

Return type:

npt.NDArray[np.float64]

run(measurements, *, controls=None)[source]

Filter a measurement sequence; return state estimates (n_steps, n).

Row k of controls is the input logged with measurements[k]; the zero-order-hold timing of step() applies (continuing from any previous step() calls on this filter).

Raises:

ValueError – If measurements is not 2-D with n_outputs columns, or controls has a different number of rows.

Parameters:

measurements (npt.NDArray[np.float64])
controls (npt.NDArray[np.float64] | None)

Return type:

npt.NDArray[np.float64]

filter_consistency(result, *, confidence=0.95)[source]

Check a run’s NIS sequence against its chi-square expectation (NIS test).

For a correctly tuned filter each step’s NIS, computed from the predicted covariance before any gate decision, is chi-square distributed with as many degrees of freedom as channels reported, so the sum over the tested steps is chi-square with dof = the total number of channels in those innovations (result.n_active summed) – a partial available mask, which lowers a step’s dof, is accounted for. Steps rejected by an outlier gate are included: keeping only the accepted ones would test a chi-square truncated at the gate, whose mean is lower, so a correctly tuned, gated filter would be reported as under-confident. A mean NIS far outside the acceptance band means the filter is over-confident (R/Q too small) or under-confident (too large) – a tuning fault that would otherwise be invisible – or that the record holds more outliers than the model’s noise explains.

Parameters:

result (FilterResult) – A trajectory from run_filter().
confidence (float, optional) – Two-sided confidence level for the acceptance band (default 0.95).

Returns:

ConsistencyReport – The mean NIS, its expectation, the acceptance band, and the outcome.

Raises:

ValueError – If no step has a finite NIS to test, or confidence is not in (0, 1).

Return type:

ConsistencyReport

Notes

A step with a finite NIS but n_active == 0 (a gated step recorded without the degrees of freedom of its rejected innovation) carries no degrees of freedom and is left out.

reconstruct_load(result, load_map, *, smoothed=None)[source]

Read a linear load off the estimated state with its propagated uncertainty.

For a load functional \(z = L x\), returns the reconstructed load \(\hat z_k = L \hat x_k\) and its standard deviation \(\sqrt{\operatorname{diag}(L P_k L^{\mathsf T})}\) at each step – the virtual sensor and its error bar.

Parameters:

result (FilterResult) – A trajectory from run_filter().
load_map (npt.NDArray[np.float64]) – The load functionals L, shape (n_loads, n_states).
smoothed (tuple or None, optional) – A (states, covariances) pair from rts_smoother() to read the load from the smoothed estimate instead of the filtered one.

Returns:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]] – The reconstructed loads (n_steps, n_loads) and their standard deviations (n_steps, n_loads).

Raises:

ValueError – If load_map does not match the state dimension or is non-finite.

Return type:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]

rts_smoother(model, result)[source]

Refine a filtered run with the Rauch-Tung-Striebel backward pass.

The smoother conditions each state on the whole record (not just the past), which an offline audit can afford: it lowers the variance and removes the filter’s lag. The control inputs enter only through the run’s recorded predictions (result.predicted_states, formed with the zero-order-hold timing of run_filter()), so the backward pass needs no controls of its own.

Parameters:

model (KalmanModel) – The same discrete model the run used (for A).
result (FilterResult) – A trajectory from run_filter().

Returns:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]] – The smoothed state means (n_steps, n_states) and covariances (n_steps, n_states, n_states).

Return type:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]

run_filter(model, measurements, *, controls=None, available=None, gate=None, gate_probability=None, initial_state=None, initial_control=None)[source]

Run a Kalman filter over a measurement sequence and record the trajectory.

Control timing (zero-order hold). Row k of controls is the input u_k logged alongside measurements[k]. Consistent with the ZOH discretization, the recursion is

\[\mathbf x_k^- = \mathbf A\mathbf x_{k-1}^+ + \mathbf B\mathbf u_{k-1}, \qquad \nu_k = \mathbf z_k - (\mathbf C\mathbf x_k^- + \mathbf D\mathbf u_k),\]

i.e. the prediction into step k uses the previous sample’s control and the current control enters only the feedthrough. initial_state (with the model’s P0) is the prior at step -1, one step before measurements[0]; the first prediction is driven by initial_control (u_{-1}), which defaults to controls[0] – the input held at its first logged value before the record, so a constant input gives exactly the same result as holding it throughout.

Parameters:

model (KalmanModel) – The discrete model and covariances.
measurements (npt.NDArray[np.float64]) – Measured outputs, shape (n_steps, n_outputs).
controls (npt.NDArray[np.float64] or None, optional) – Control inputs logged with the measurements, shape (n_steps, n_inputs); None for an autonomous model.
available (npt.NDArray[np.bool] or None, optional) – Per-step channel mask, shape (n_steps, n_outputs); None uses all channels at every step. Use this to encode sensor dropout.
gate (float or None, optional) – A fixed chi-square NIS threshold for per-step outlier rejection (not scaled by the number of reporting channels).
gate_probability (float or None, optional) – Outlier-gate acceptance probability in (0, 1); each step’s threshold is the chi-square quantile for its number of reporting channels. Mutually exclusive with gate.
initial_state (npt.NDArray[np.float64] or None, optional) – Prior state mean one step before measurements[0]; defaults to zeros.
initial_control (npt.NDArray[np.float64] or None, optional) – The input u_{-1} driving the first prediction; defaults to controls[0]. Pass zeros for a plant at rest (no input) before the record. Requires controls.

Returns:

FilterResult – The filtered and predicted state means/covariances, per-step NIS, and acceptance flags.

Raises:

ValueError – If measurements is not 2-D with n_outputs columns, controls / available lengths disagree with it, initial_control is given without controls, or the gate arguments are invalid.

Return type:

FilterResult

Kalman covariance initialization, informed by mode-identification uncertainty.

A Kalman filter needs a process-noise covariance Q, a measurement-noise covariance R, and an initial state covariance P0. When the modes were classified with uncertainty quantification, that uncertainty is propagated into P0: a mode identified with low confidence is given a larger initial variance, so the filter trusts well-identified modes more than ambiguous ones.

class CovarianceSet(q, r, p0)[source]

Bases: object

Kalman-filter covariance matrices.

Parameters:

q (npt.NDArray[np.float64]) – Process-noise covariance, shape (n_states, n_states).
r (npt.NDArray[np.float64]) – Measurement-noise covariance, shape (n_outputs, n_outputs).
p0 (npt.NDArray[np.float64]) – Initial state covariance, shape (n_states, n_states).

q: npt.NDArray[np.float64]

r: npt.NDArray[np.float64]

p0: npt.NDArray[np.float64]

covariances_from_confidence(confidences, n_outputs, *, process_noise=0.0001, measurement_noise=0.01, base_variance=1.0, uncertainty_scale=10.0)[source]

Build covariances whose P0 grows with mode-identification uncertainty.

Each mode maps to two modal states (real and imaginary parts); the initial variance of those states is base_variance * (1 + uncertainty_scale * (1 - confidence)), so a low-confidence mode starts with a larger covariance.

Parameters:

confidences (Sequence[float]) – Per-mode identification confidence in [0, 1]; values are clipped to that range.
n_outputs (int) – Number of measured outputs.
process_noise (float, optional) – Diagonal values for Q and R; must be non-negative.
measurement_noise (float, optional) – Diagonal values for Q and R; must be non-negative.
base_variance (float, optional) – Initial variance of a fully confident mode; must be non-negative.
uncertainty_scale (float, optional) – How strongly uncertainty inflates the initial variance; must be non-negative.

Returns:

CovarianceSet – The covariance matrices, with 2 * len(confidences) states.

Raises:

ValueError – If a noise value, base_variance, uncertainty_scale, or n_outputs is negative or non-finite, or a confidence is non-finite.

Return type:

CovarianceSet

initialize_covariances(n_states, n_outputs, *, process_noise=0.0001, measurement_noise=0.01, initial_variance=1.0)[source]

Build uniform diagonal covariance matrices.

Parameters:

n_states (int) – Number of states.
n_outputs (int) – Number of measured outputs.
process_noise (float, optional) – Diagonal values for Q, R, and P0 respectively; all must be non-negative.
measurement_noise (float, optional) – Diagonal values for Q, R, and P0 respectively; all must be non-negative.
initial_variance (float, optional) – Diagonal values for Q, R, and P0 respectively; all must be non-negative.

Returns:

CovarianceSet – The diagonal covariance matrices.

Raises:

ValueError – If a dimension is negative, or a noise value or initial_variance is negative or non-finite.

Return type:

CovarianceSet

Process- and measurement-noise covariances for the discrete estimator.

A Kalman filter on a discretized model needs a discrete process-noise covariance \(\mathbf Q_d\) consistent with the continuous model it came from, not a hand-picked diagonal. This module builds the covariances the reduced estimator consumes:

discretize_process_noise() converts a continuous process-noise spectral density \(\mathbf Q_c\) to the exact discrete covariance \(\mathbf Q_d=\int_0^{\Delta t}e^{\mathbf A s}\mathbf Q_c e^{\mathbf A^{\mathsf T} s}\,\mathrm ds\) over one step, by the Van Loan block-exponential identity — the discretization that matches the zero-order-hold A_d the state space already uses.
modal_process_noise() assembles a block-diagonal continuous \(\mathbf Q_c\) for the real modal realization (two states per mode), one intensity per mode, so the per-mode process noise can be set from each mode’s damping and identification uncertainty rather than a single global value.
measurement_noise_from_specs() turns per-channel sensor noise standard deviations into the diagonal measurement-noise covariance \(\mathbf R\).

Together they replace the placeholder diagonal Q/R with covariances traceable to the continuous model and the sensor specifications.

discretize_process_noise(a, spectral_density, dt)[source]

Discretize a continuous process-noise spectral density over one step.

Computes the discrete process-noise covariance

\[\mathbf Q_d = \int_0^{\Delta t} e^{\mathbf A s}\,\mathbf Q_c\, e^{\mathbf A^{\mathsf T} s}\,\mathrm d s\]

exactly, by the Van Loan block-exponential identity: for \(\mathbf F = \begin{bmatrix}-\mathbf A & \mathbf Q_c\\ \mathbf 0 & \mathbf A^{\mathsf T}\end{bmatrix}\), with \(e^{\mathbf F\Delta t}=\begin{bmatrix}\mathbf G_{11}&\mathbf G_{12}\\ \mathbf 0&\mathbf G_{22}\end{bmatrix}\), the discrete-time transition is \(\mathbf A_d=\mathbf G_{22}^{\mathsf T}\) (equal to the zero-order-hold \(e^{\mathbf A\Delta t}\)) and \(\mathbf Q_d=\mathbf A_d\mathbf G_{12}\). This is the process-noise companion to the ZOH discretization of (A, B).

The block exponentiates \(-\mathbf A\), which grows for stable modes; for a stiff system that intermediate overflows before the cancellation. To stay finite and well conditioned for stiff, near-marginal, and mixed systems alike, the step is split into \(2^k\) equal sub-steps small enough that the block is well behaved, and the sub-step covariance is recombined by doubling, \(\mathbf Q_d(2\tau)=\mathbf Q_d(\tau)+\boldsymbol\Phi(\tau)\mathbf Q_d(\tau) \boldsymbol\Phi(\tau)^{\mathsf T}\) with \(\boldsymbol\Phi=e^{\mathbf A\tau}\). No stability is required.

Parameters:

a (npt.NDArray[np.float64]) – Continuous-time system matrix, shape (n_states, n_states).
spectral_density (npt.NDArray[np.float64]) – Continuous process-noise spectral density Q_c, a symmetric positive semidefinite matrix of shape (n_states, n_states).
dt (float) – Sample step Δt (must be positive and finite).

Returns:

npt.NDArray[np.float64] – The discrete process-noise covariance Q_d, a symmetric (n_states, n_states) matrix.

Raises:

ValueError – If a is not square, spectral_density does not match a, is not a valid (symmetric positive-semidefinite) covariance, or dt is not positive and finite.

Return type:

npt.NDArray[np.float64]

measurement_noise_from_specs(noise_std)[source]

Build the measurement-noise covariance from per-channel noise specs.

Each sensor’s noise standard deviation maps to a variance on the diagonal of R, so the measurement-noise covariance is traceable to the instrument specifications rather than a single global guess.

Parameters:: noise_std (Sequence[float]) – Per-channel noise standard deviation (one per sensor), all non-negative, in the sensor’s measurement units.
Returns:: npt.NDArray[np.float64] – The diagonal measurement-noise covariance R = diag(noise_std**2) of shape (n_sensors, n_sensors).
Raises:: ValueError – If any standard deviation is negative or non-finite.
Return type:: npt.NDArray[np.float64]

modal_process_noise(intensities)[source]

Build a block-diagonal continuous process-noise density over modal states.

The real modal realization carries two states per mode; this places one intensity on each mode’s two states, giving the continuous spectral density Q_c for discretize_process_noise(). Setting a larger intensity on a less-trusted or more lightly damped mode lets the filter admit more drift there.

Parameters:: intensities (Sequence[float]) – Per-mode process-noise intensity (one value per mode), all non-negative.
Returns:: npt.NDArray[np.float64] – The block-diagonal spectral density Q_c of shape (2 * n_modes, 2 * n_modes), with intensities[k] on the two states of mode k.
Raises:: ValueError – If any intensity is negative or non-finite.
Return type:: npt.NDArray[np.float64]

Unknown-input (disturbance) augmentation for load virtual sensing.

A reduced model reconstructs states from sensors, but the quantity a digital twin ultimately wants is often an unknown input — the wave/wind load or mooring force that drives the structure and is never measured. The standard way to estimate it is to append a model of the disturbance to the state space and let the filter estimate the augmented state; the disturbance estimate is then read straight off it.

Given a physical continuous model

\[\dot{\mathbf x} = \mathbf A\mathbf x + \mathbf B\mathbf u + \mathbf E\mathbf d, \qquad \mathbf y = \mathbf C\mathbf x + \mathbf D\mathbf u + \mathbf F\mathbf d,\]

and a disturbance shaping model \(\dot{\mathbf z} = \mathbf A_d\mathbf z + \mathbf w\), \(\mathbf d = \mathbf C_d\mathbf z\) (white \(\mathbf w\)), the augmented system on \([\mathbf x; \mathbf z]\) is

\[\begin{split}\mathbf A_{\text{aug}} = \begin{bmatrix}\mathbf A & \mathbf E\mathbf C_d\\ \mathbf 0 & \mathbf A_d\end{bmatrix},\quad \mathbf B_{\text{aug}} = \begin{bmatrix}\mathbf B\\ \mathbf 0\end{bmatrix},\quad \mathbf C_{\text{aug}} = \begin{bmatrix}\mathbf C & \mathbf F\mathbf C_d\end{bmatrix},\end{split}\]

with the disturbance recovered from the augmented state by \(\hat{\mathbf d} = \begin{bmatrix}\mathbf 0 & \mathbf C_d\end{bmatrix} [\mathbf x; \mathbf z]\).

random_walk_disturbance() models a slowly-varying (quasi-constant) unknown load; harmonic_disturbance() models a narrowband load at a known frequency — the natural choice for wave-frequency mooring and platform loads. augment_with_disturbance() assembles the augmented state space, the disturbance-recovery map, and the augmented process-noise spectral density (ready for discretize_process_noise()). This construction is deterministic and auditable, so it lives in the model factory and not ad hoc in the estimator runtime.

class AugmentedModel(system, recovery, spectral_density, n_disturbance_states)[source]

Bases: object

A state space augmented with a disturbance model and the recovery map.

Parameters:

system (StateSpace) – The augmented continuous state space on [x; z] (physical states first, then disturbance states), with the physical inputs and outputs preserved.
recovery (npt.NDArray[np.float64]) – The disturbance-recovery map, shape (n_signals, n_aug_states); the disturbance estimate is d_hat = recovery @ x_aug.
spectral_density (npt.NDArray[np.float64]) – The augmented continuous process-noise spectral density, shape (n_aug_states, n_aug_states) — the physical process noise (or zero) on the physical block and the disturbance intensity on the disturbance block.
n_disturbance_states (int) – Number of appended disturbance states.

system: StateSpace

recovery: npt.NDArray[np.float64]

spectral_density: npt.NDArray[np.float64]

n_disturbance_states: int

class DisturbanceModel(a, c, intensity, state_names)[source]

Bases: object

A linear shaping model of an unknown disturbance/load.

The disturbance d is the output of a small linear system driven by white noise, z' = a z + w, d = c z, with w a continuous white process of spectral density intensity. Different a/c give different prior shapes (a random walk, a harmonic oscillator, …).

Parameters:

a (npt.NDArray[np.float64]) – Disturbance internal dynamics, shape (n_dist_states, n_dist_states).
c (npt.NDArray[np.float64]) – Disturbance output map, shape (n_signals, n_dist_states); d = c z has n_signals channels.
intensity (npt.NDArray[np.float64]) – Continuous process-noise spectral density of the disturbance states, a symmetric positive-semidefinite (n_dist_states, n_dist_states) matrix.
state_names (list[str]) – Names of the disturbance states (length n_dist_states; may be empty).

a: npt.NDArray[np.float64]

c: npt.NDArray[np.float64]

intensity: npt.NDArray[np.float64]

state_names: list[str]

augment_with_disturbance(system, disturbance, *, entry, output_entry=None, process_noise=None)[source]

Append a disturbance model to a state space for unknown-input estimation.

Builds the augmented continuous system on [x; z] with the disturbance entering the physical dynamics through entry (x' += entry @ d). An optional output_entry preserves direct disturbance-to-output feedthrough (y += output_entry @ d). The physical inputs and outputs are otherwise preserved, and the disturbance is recovered from the augmented state.

Parameters:

system (StateSpace) – A continuous-time physical model (dt is None).
disturbance (DisturbanceModel) – The disturbance shaping model (e.g. from random_walk_disturbance() or harmonic_disturbance()).
entry (npt.NDArray[np.float64]) – Input map of the disturbance into the physical state derivative, shape (n_states, n_signals) where n_signals is disturbance.c’s row count. Often a column block of B (the load enters where a known input does).
output_entry (npt.NDArray[np.float64] or None, optional) – Direct disturbance-to-output map, shape (n_outputs, n_signals). This is the disturbance column block removed from the physical system’s D matrix when an originally known input is promoted to an augmented state. None means there is no direct disturbance feedthrough.
process_noise (npt.NDArray[np.float64] or None, optional) – Continuous process-noise spectral density of the physical states, shape (n_states, n_states). None uses zero physical process noise.

Returns:

AugmentedModel – The augmented system, the disturbance-recovery map, the augmented process-noise spectral density, and the disturbance-state count.

Raises:

ValueError – If system is discrete, entry/output_entry do not match the physical system and disturbance signals, or process_noise has the wrong shape.

Return type:

AugmentedModel

combine_disturbance_models(disturbances)[source]

Combine independent disturbance models without changing their signals.

The returned shaping model is the block-diagonal union of the supplied dynamics and process-noise intensities. Its output matrix is block diagonal as well, so the physical disturbance signals remain ordered by model and are not summed. This is useful for mixed priors such as aerodynamic torque as a random walk and incident wave elevation as a narrowband oscillator.

Parameters:: disturbances (Sequence[DisturbanceModel]) – Non-empty sequence of validated shaping models.
Returns:: DisturbanceModel – Independent block-diagonal union of every state and signal channel.
Return type:: DisturbanceModel

gauss_markov_disturbance(time_constants_s, intensity, *, n_signals=1, name='load')[source]

Model bounded load perturbations as independent first-order processes.

Each signal follows z' = -z / tau + w and d = z. The operating-point baseline is supplied by the surrounding linear model, so the prior mean remains zero in perturbation coordinates while tau prevents an unconstrained random walk from drifting indefinitely. This is suitable for scheduled controller-regulated loads such as above-rated aerodynamic torque.

Parameters:

time_constants_s (float or Sequence[float]) – Positive finite mean-reversion time constant per signal in seconds.
intensity (float or Sequence[float]) – Non-negative continuous process-noise intensity per signal.
n_signals (int, optional) – Number of independent signals; default one.
name (str, optional) – Base name for the disturbance states.

Return type:

harmonic_disturbance(frequencies_hz, intensity, *, name='wave')[source]

Model unknown loads as narrowband oscillators at known frequencies.

Each frequency contributes a two-state undamped oscillator [[0, ω], [-ω, 0]] (ω = 2π f) driven by white noise, with the disturbance read from its first state. This is the natural prior for a wave-frequency load whose frequency is known but whose amplitude and phase are not.

Parameters:

frequencies_hz (Sequence[float]) – Oscillator frequencies in Hz, all finite and positive. One disturbance channel (and two states) per frequency.
intensity (float or Sequence[float]) – Continuous process-noise intensity driving each oscillator (applied to both of its states); a scalar applies to all, or one value per frequency. Non-negative.
name (str, optional) – Base name for the disturbance states ("{name}_{i}_{re,im}").

Returns:

DisturbanceModel – A harmonic disturbance model with 2 * len(frequencies_hz) states and one output channel per frequency.

Raises:

ValueError – If no frequencies are given, any frequency is non-finite or not positive, intensity has the wrong length, or any intensity is negative.

Return type:

random_walk_disturbance(intensity, *, n_signals=1, name='load')[source]

Model unknown loads as independent random walks (quasi-constant inputs).

Each disturbance channel is integrated white noise (z' = w, d = z), the standard prior for a slowly-varying or constant unknown input. One disturbance state per channel.

Parameters:

intensity (float or Sequence[float]) – Continuous process-noise intensity of each random walk; a scalar applies to all channels, or one value per channel. All values must be non-negative.
n_signals (int, optional) – Number of independent disturbance channels (default 1).
name (str, optional) – Base name for the disturbance states ("{name}_{i}").

Returns:

DisturbanceModel – A random-walk disturbance model with n_signals states.

Raises:

ValueError – If n_signals is not positive, intensity has the wrong length, or any intensity is negative.

Return type:

random_walk_harmonic_disturbance(frequencies_hz, random_walk_intensity, harmonic_intensity, *, name='load')[source]

Model one unknown load as a DC random walk plus scheduled harmonics.

Unlike harmonic_disturbance(), whose frequencies are separate disturbance channels, this construction sums every component into one physical signal: d = z_dc + sum(z_h,re). It is intended for a rotor load containing a slowly varying component together with known 1P/3P orders. Amplitudes and phases remain estimated states; only the physics-derived frequencies are prescribed.

Parameters:

frequencies_hz (Sequence[float]) – Positive harmonic frequencies in hertz.
random_walk_intensity (float) – Continuous process-noise intensity of the DC random-walk state.
harmonic_intensity (float or Sequence[float]) – Continuous process-noise intensity per harmonic oscillator. A scalar broadcasts; each value is applied to both quadrature states.
name (str, optional) – Base name for the DC and harmonic states.

Return type: