model_order¶

MATLAB equivalent: sidModelOrder

model_order ¶

Estimate model order from frequency response via Hankel SVD.

model_order ¶

model_order(result: object, *, horizon: int | None = None, threshold: float | None = None) -> tuple[int, dict]

Estimate model order from frequency response data.

This is the Python port of sidModelOrder.m.

Estimates the state dimension n of a linear system from the singular value decomposition of a block Hankel matrix built from impulse response coefficients. The impulse response is obtained via IFFT of the frequency response estimate.

Parameters:

Name	Type	Description	Default
`result`	`FreqResult`	Result from any `sid.freq_*` function. Must expose `.response`, `.noise_spectrum`, and `.frequency` attributes. For time-series data (no input), `response` may be `None`; in that case `.noise_spectrum` is used.	required
`horizon`	`int or None`	Block Hankel prediction horizon r. Default: `min(N_imp // 3, 50)`.	`None`
`threshold`	`float or None`	If specified, count singular values with `sigma_k / sigma_1 > threshold` instead of gap detection. Default: `None` (use gap method).	`None`

Returns:

Name	Type	Description
`n`	`int`	Estimated model order (state dimension).
`sv_dict`	`dict`	Dictionary with keys: `'singular_values'` -- 1-D ndarray of singular values. `'horizon'` -- int, prediction horizon used.

Raises:

Type	Description
`SidError`	If result is missing required attributes (code: `'bad_input'`).
`SidError`	If horizon is not a positive integer (code: `'bad_horizon'`).
`SidError`	If threshold is not a positive scalar (code: `'bad_threshold'`).
`SidError`	If the impulse response is too short for a Hankel matrix (code: `'too_short'`).

Examples:

Automated model order detection:

>>> import sid
>>> G = sid.freq_bt(y, u)
>>> n, sv = sid.model_order(G)

With a threshold:

>>> n, sv = sid.model_order(G, threshold=0.01)

Notes

Specification: SPEC.md section 8.12 -- Output-COSMIC: Partial State Observation

Algorithm:

Compute impulse response g(k) via IFFT of the frequency response, using a conjugate-symmetric extension to obtain a real-valued sequence.
Build block Hankel matrix H with r block-rows and r block-columns. For MIMO systems each entry g(k) is an (ny, nu) block.
Compute SVD of H.
Detect model order as argmax_k (sigma_k / sigma_{k+1}) (gap method) or count singular values above threshold.

References:

Kung, S.Y. "A new identification and model reduction algorithm via singular value decomposition." Proc. 12th Asilomar Conference, 1978.