Fable OSI Parameter Tuning Map
This page maps the current Fable OSI implementation to its Speedgoat
runtime parameters. It uses the same notation as the code:
dd, dm, b_osi,
b_st, b_res, b_fast,
auth, fbls, and fbla.
Source Map
| File | Role | Important notation |
|---|---|---|
main_ColumnSetup.m |
Top-level RTHS setup. Sets hs.exp_tf_file, hs.osi_gain_initial, hs.osi_gain_min, hs.target_outer_ncf, then calls prepare_fable_runtime(projectFolder, dt, hs). |
hs, dt, fs, fable_setup, logged columns auth, b_osi, b_st, b_res, b_fast, trip_reason, valid, decision. |
control_and_HS/OSI/prepare_fable_runtime.m |
Loads the identified H_dc_dm, builds PID C, creates the Fable OSI config and authority params, then flattens them for Simulink. |
fbls, fblw, fblbins, fblfw, fblfbins, fblag, fbla. |
control_and_HS/OSI/fable_osi_runtime.m |
Speedgoat-compatible runtime. Called once per base-rate sample. It time-slices one OSI update across 56 ticks and publishes held outputs. | dd, dm, en, auth, b_osi, b_st, b_res, b_fast. |
OSI_tests/fable/fable_osi.m |
Desktop estimator and tuning guide. This is the readable source for the slow ST branch, residual branch, fast quick-dip guards, calibration, and prediction curve. | cfg, state, info, pred_margin, alpha_grid. |
OSI_tests/fable/fable_auth.m |
Desktop authority law and tuning guide. The runtime function fableAuthStep is a flattened version of this logic. |
prm, ast, a_next, decision. |
simulink_changes.md |
Documents the current Speedgoat overload fix: time-sliced Fable OSI, direct enable wiring, and logged Fable margins. | P_PUB = 56, 27 ms publish latency, measured TETMax 278 us. |
hs.osi_branch_split_hz, hs.osi_st_branch_hz,
and hs.osi_residual_branch_hz are legacy M9.1 fields.
The current Fable path does not consume them in
prepare_fable_runtime. Tune Fable branch behavior through
hs.fable_osi_override, especially
residual_band_hz, not those legacy fields.
Arguments And Runtime Signals
prepare_fable_runtime(projectFolder, dt, hs)
| Argument or field | Definition | Behavior controlled |
|---|---|---|
projectFolder | Path to main. Used to load saved exp_tf files through project helpers. | File resolution only. |
dt | Base sample period in seconds. Current code uses dt = 1/2048. | All window sizes and runtime step sizes. |
hs.exp_tf_file | Saved transfer-function file containing H_dc_dm and usually pid_values. | Nominal loop L0 = C*H_dc_dm used for the nominal margin curve and residual anchor. |
hs.target_outer_ncf | Top-level target margin. In Fable it becomes cfg.threshold and prm.target. | Main safety/performance setpoint. Higher is more conservative. |
hs.osi_gain_min | Authority floor. Becomes prm.a_min. | Deepest authority shed allowed. |
hs.osi_gain_initial | Startup and shadow-mode authority. Becomes prm.a_init. | Initial product gain at Apply OSI gain. |
hs.fable_osi_override | Struct whose fields override cfg from fable_osi('config', ...). | Estimator branch tuning: ST, residual, fast quick-dip, calibration, prediction grid. |
hs.fable_auth_override | Struct whose fields override prm from fable_auth('params', ...). | Authority behavior: shed, recovery, trips, latch, commit gate. |
hs.fable_pred_enable | Optional boolean flattened into fbls(55). Default is 1. | Set 0 to skip the prediction grid and reduce TET load. |
fable_osi_runtime(dd, dm, en, fbls, fblw, fblbins, fblfw, fblfbins, fblag, fbla)
| Argument | Definition |
|---|---|
dd | Numerical command displacement sample in mm. This is the loop command used as the OSI input. |
dm | Measured actuator displacement sample in mm. This is the OSI output. |
en | Enable code. 0 means shadow mode: estimate and log, but force auth = a_init. 1 publishes the authority law. en >= 2 triggers the pause contract inside the runtime, though current model wiring sends enable directly and does not pause the indicator with dd_pause_enable. |
fbls | Scalar OSI config vector. Index map is in prepare_fable_runtime and unpacked in unpackConfig. |
fblw | Slow Hann window, length segment_n. |
fblbins | Slow-bin table: [freq_hz, fft_bin, keep, res_keep, nominal_curve]. |
fblfw | Fast Hann window, length fast_segment_n. |
fblfbins | Fast-bin table: [freq_hz, fft_bin, keep, cell_lo, cell_hi, band_id]. |
fblag | Authority-prediction relative gain grid alpha_grid. |
fbla | Authority-law parameter vector. Index map is in prepare_fable_runtime and consumed by fableAuthStep. |
Runtime outputs
| Output | Definition | Log meaning |
|---|---|---|
auth | Authority factor applied at the Apply OSI gain Product. | Column auth. Lower means less loop authority. |
b_osi | Selected Fable margin: slow selected margin, and during a fast ST trip it is allowed to show min(b_osi, b_fast). | Main OSI value to compare with target_outer_ncf. |
b_st | Slow coherent ST branch margin. | Evidence from bins driven by dd with enough coherence and input power. |
b_res | Slow residual/quiet-band branch margin. | Evidence from output power growth in undriven hazard bands. |
b_fast | Fast short-memory ST margin. | Quick-dip / sudden collapse indicator. |
trip_reason | 0 none, 1 quiet-band burst trip, 2 fast FRF-collapse trip. | Why immediate authority shed was triggered. |
valid | 1 when b_osi is real post-warm-up evidence, 0 otherwise. | Do not treat NaN/warm-up as a real safety margin. |
decision | 0 hold, 1 down, 2 severe down, 3 up, 4 fast trip. | Authority-law state machine output. |
Core Equations
fs = 1/dtsegment_n = round(segment_s*fs)step_n = round(step_s*fs)n_segment = round((window_s - segment_s)/hop_s) + 1
The OSI estimates the closed-loop transfer from command displacement to
measured displacement. In the code, M = Suy/Suu, where
Suu is command autospectrum, Syy is measured
autospectrum, and Suy is cross spectrum.
g2raw = abs(Suy)^2 / max(Suu*Syy, tiny^2)gamma2 = max(0, (k_eff*g2raw - 1)/(k_eff - 1))excited = keep & g2raw > gamma_gate & has_input & not_leakquiet = res_keep & ~has_input & g2raw < gamma_quiet
The project margin is the normalized coprime-factor style chordal
margin. With T = M and S = 1 - T:
b(w) = 1/(sqrt(2)*sqrt(abs(S)^2 + abs(T)^2))b_st = min_over_excited_bins( masked_median_frequency(b(w)) )b_osi = min(b_st, b_res), capped by cap = 1/sqrt(2)
The residual branch watches output power that is not explained by the coherent command path.
res = Syy * max(1 - gamma2, residual_floor)ratio = res / baselinenormq = ratio / max(median(ratio(quiet)), eps)z = (log(max(normq, eps)) - mu0) / sigma0growth = exp(max(z_max, 0)*sigma0)b_res = max(0.05, anchor/sqrt(max(growth, 1)))
The fast quick-dip logic uses CUSUM statistics. Lower drift
nu or threshold h makes detection faster and
more sensitive.
cus_st = max(0, cus_st + z_d - fast_st_nu)st_trip = cus_st > fast_st_h & b_fast < b_slow_filt & b_fast < threshold + fast_babs_offsetcus_burst(j) = max(0, cus_burst(j) + z_burst(j) - fast_burst_nu)burst_trip = any(cus_burst > fast_burst_h)
The authority law regulates b_osi toward
prm.target. It lowers authority quickly when margin is low
and recovers only after hysteresis and hold-time checks pass.
filt_alpha = 1 - exp(-dt_update/b_filt_tau_s)b_filt = (1 - filt_alpha)*b_filt + filt_alpha*bsevere = b < sev_frac*targetlow = min(b, b_filt) < target - down_deadbanda_pl = a_cont * (max(b_size, 0.02)/target)^down_powera_cont = min(a_cont, max(a_shed_tgt, a_cont - rate*dt_update))recovery_rate = up_rate*(1 + up_prop*surplus/target)
Slow ST Branch Parameters
The slow ST branch is the accurate margin level when the command
excites the dangerous frequencies. It is the best branch for recovery
decisions because it observes the actual coherent transfer
T = dm/dd.
| Parameter | Default | Definition | Tuning effect |
|---|---|---|---|
band_hz | [2 100] | Overall frequency band considered by the OSI. | Narrowing reduces cost and ignores irrelevant modes; widening watches more modes but can add noisy bins. |
line_reject_hz | [58 62] | Power-line rejection band removed from slow and fast grids. | Move only if electrical line contamination is elsewhere. |
segment_s | 1.0 | Hann segment length for slow spectra. | Keep near 1 s for 1 Hz resolution. Shorter weakens margin frequency resolution. |
hop_s | 0.25 | Slow spectral refresh cadence. Must be compatible with step_s. | Larger is cheaper and smoother but slower; smaller is faster but heavier. |
step_s | 0.125 | Runtime OSI step cadence and fast path cadence. | Larger lowers Speedgoat work; smaller improves quick-dip reaction but costs TET. |
window_s | 5.0 | Slow ring memory. Produces n_segment median-aggregated segments. | Longer gives stable margins; shorter follows changes faster but can false dip. |
gamma_alpha | 0.01 | False-pass probability used to derive gamma_gate. | Lower is stricter, accepting fewer coherent bins. |
input_power_range_db | 35 | Bins this far below the in-band input peak are considered unexcited. | Lower accepts only stronger command bins; higher accepts weaker bins. |
sidelobe_db | 25 | Rejects bins that look like Hann leakage from a nearby stronger bin. | Raise to be stricter about leakage; lower to keep more adjacent bins. |
min_bins | 5 | Minimum excited slow bins required for b_st. | Raise to reduce false ST decisions; lower to allow sparse excitation. |
freq_medfilt_n | 3 | Median filter width across frequency bins. | Raise to ignore single-bin dips; keep odd because runtime median assumes odd centered windows. |
margin_filter_n | 3 | Temporal median over distinct slow updates before publishing selected slow margin. | Raise for smoother b_osi; adds about (n-1)*hop_s/2 lag. |
slow_filt_alpha | 0.2 | EMA weight for b_slow_filt, used by fast path direction gate. | Lower makes fast-trip reference steadier; higher follows level changes faster. |
warm_updates | 4 | Number of slow updates before margins are reported. | Raise to avoid startup artifacts; lower for earlier evidence. |
cap | 1/sqrt(2) | Mathematical maximum of the chordal margin. | Not a normal tuning knob. |
threshold | target_outer_ncf | Detection threshold and fast-trip absolute level. | Higher is more conservative; must be reachable by the healthy full-authority loop. |
alpha_grid | logspace(log10(0.05), log10(20), 25) | Relative loop-gain grid for predicting safe authority changes. | More points improve recovery/shed boundary resolution but cost runtime work. |
pred_denom_floor | 1e-3 | Floor on 1 - M when converting T to loop gain for prediction. | Prevents numerical blow-up near T = 1. |
Residual Branch Parameters
The residual branch watches the hazard band when the command does not excite it. It is slower than the fast branch because it needs a calibrated quiet-band baseline, but it is the branch that protects against uncommanded growth.
| Parameter | Default | Definition | Tuning effect |
|---|---|---|---|
residual_band_hz | [28 100] | Hazard band where quiet-bin growth is watched. | Most important residual branch-band knob. Narrow to avoid false alarms from command harmonics; widen to watch more modes. |
gamma_quiet | 0.15 | Maximum raw coherence for a bin to count as quiet. | Lower is stricter quiet selection; higher allows more bins into residual evidence. |
residual_floor | 0.03 | Minimum fraction in res = Syy*max(1 - gamma2, residual_floor). | Prevents residual power from going to zero under high coherence. |
cal_skip_s | 10 | Startup blackout before accepting residual calibration windows. | Raise if startup transients poison baseline. |
cal_windows | 80 | Accepted slow-hop windows needed for full calibration. | More gives stronger baseline; fewer calibrates faster. |
cal_min_windows | 24 | Minimum accepted windows if timeout occurs. | Lower calibrates under difficult data but weakens statistics. |
cal_timeout_hops | 600 | Slow-hop attempts before timeout path can accept cal_min_windows. | Lower allows earlier readiness after many rejects. |
cal_reject_factor | 4 | Rejects calibration windows whose broadband residual median is more than this factor from reference. | Lower rejects more startup/outlier windows; higher is more permissive. |
cal_restart_rejects | 12 | Consecutive rejects that restart calibration collection. | Lower recovers faster from a bad initial reference. |
z_on | 4.0 | Z-score threshold to engage residual branch. | Lower detects earlier but risks false engagement; raise for fewer false alarms. |
z_off | 2.0 | Z-score threshold below which engagement decays. | Controls hysteresis. Lower holds residual engagement longer. |
res_on_n | 4 | Consecutive slow hops above z_on needed to engage. | Lower reacts faster; higher needs sustained evidence. |
res_hold_s | 5 | Time engagement may persist in the hysteresis zone without reconfirmation. | Raise to hold caution longer; lower to recover faster from one-off events. |
res_min_growth_db | 3 | Absolute growth required in addition to z_on. | Raise to ignore small quiet-band changes. |
res_match_hz | 3 | Frequency persistence tolerance for the residual peak. | Lower requires same-bin persistence; higher tolerates drifting mode frequency. |
sigma0_floor | 0.15 | Floor on calibrated log-ratio spread. | Raise to desensitize residual z-scores globally. |
bl_adapt_tau_s | 100 | Time constant for healthy quiet-band baseline drift. | Lower tracks benign drift faster but risks absorbing real degradation. |
bl_adapt_max_db | 3 | Hard baseline adaptation cap around original baseline. | Raise only if benign drift exceeds 3 dB; too high can hide damage. |
regime_hops | 8 | Sustained input-support changes before residual rebaseline. | Lower rebaselines earlier on test phase changes; higher avoids unnecessary recalibration. |
Fast Quick-Dip Parameters
The fast branch is not the main recovery authority. It is the quick
protection path for sudden margin dips, FRF collapse, and quiet-band
bursts. Its output can force decision = 4 and immediate
authority shed.
| Parameter | Default | Definition | Tuning effect |
|---|---|---|---|
fast_segment_s | 0.25 | Fast Hann segment length. At 2048 Hz this is 512 samples. | Shorter detects sooner but gets coarse/noisy spectra; longer is calmer and slower. |
fast_ring_n | 3 | Number of fast segments in the fast median ring. | Raise for smoother b_fast; lower for faster quick-dip sensitivity. |
fast_min_bins | 3 | Minimum fast bins needed for fast ST margin. | Raise to avoid trips from sparse evidence. |
fast_st_nu | 1.25 | CUSUM drift for FRF-change statistic. | Lower accumulates evidence faster; higher reduces false trips. |
fast_st_h | 4.5 | CUSUM trip threshold for FRF-change statistic. | Main fast ST sensitivity knob. Lower means earlier trips. |
fast_babs_offset | 0.10 | Fast ST trip additionally requires b_fast < threshold + fast_babs_offset. | Raise to trip while still above target; lower to trip only near/under target. |
fast_amove_frac | 0.02 | Relative authority move that disarms the FRF-change statistic for one slow window. | Prevents the law from tripping on its own authority changes. Lower is more conservative against self-trip. |
fast_pin_lo | 0.25 | Newest command power must be at least this fraction of its EMA. | Raise to reject fading-command artifacts; lower keeps fast path armed through fades. |
fast_pin_hi | 4.0 | Newest command power must be below this multiple of its EMA. | Lower rejects command bursts more aggressively. |
fast_pin_alpha | 0.04 | EMA update weight for command-power pinning. | Higher follows changing input power faster; lower makes the pin reference steadier. |
fast_burst_bands | [28 44; 44 60; 62 78; 78 94; 94 100] | Quiet-band burst sub-bands on the fast grid. | Remove bands to reduce cost/false trips; adjust to match actual instability modes. |
fast_burst_nu | 1.0 | CUSUM drift for quiet-band burst z-scores. | Lower detects bursts faster; higher calms the detector. |
fast_burst_h | 6.0 | CUSUM trip threshold for quiet-band bursts. | Lower trips sooner; higher requires stronger sustained burst evidence. |
fast_sig_floor | 0.20 | Floor on calibrated log burst-power spread. | Raise to desensitize all burst bands. |
fast_d_sig_floor | 0.30 | Floor on calibrated log FRF-change spread. | Raise to desensitize the fast ST CUSUM. |
Speedgoat Runtime Parameters
These are mostly scheduling and flattening parameters. They control whether the algorithm fits inside the 2048 Hz real-time budget.
| Runtime item | Definition | Tuning or failure mode |
|---|---|---|
P_PUB = 56 | Publish phase in fable_osi_runtime. One 0.125 s step is time-sliced and outputs publish 56 base-rate ticks after the step boundary. | At 2048 Hz, latency is about 27 ms. This is part of the overload fix. |
pred_enable / hs.fable_pred_enable | Controls whether the prediction grid runs. | First TET reduction knob. Set 0 to skip prediction; authority then uses power-law regulation alone. |
step_s | Controls OSI step cadence and fast path cadence. | If target overruns, raising to 0.25 halves fast-path rate. |
hop_s | Controls slow path refresh cadence. | If target overruns, raising to 0.5 halves slow-pipeline rate. |
band_hz | Frequency span stored in fblbins and fblfbins. | Narrow to reduce bin count and median/prediction work. |
segment_s | Slow FFT length. | Do not shrink below 1 s unless accepting worse frequency resolution. |
freq_medfilt_n | Runtime assumes odd centered medians. | Keep odd; prepare_fable_runtime asserts this. |
en | Runtime enable code. | Current model uses direct enable wiring; the OSI keeps evaluating during command pause. |
fable_pred_enable = 0
2. step_s = 0.25
3. hop_s = 0.5
4. band_hz = [2 80]
Final Categorized Tuning Table
This table focuses only on parameters that are practical to tune to control OSI behavior. Categories are branch-based plus quick-dip and authority behavior.
| Category | Main parameters | Primary behavior controlled | Faster / more protective | Smoother / fewer false actions |
|---|---|---|---|---|
| Slow ST branch | window_s, hop_s, margin_filter_n, freq_medfilt_n, gamma_alpha, input_power_range_db, min_bins |
Accurate coherent margin b_st used for normal regulation and recovery. |
Lower window_s, lower hop_s, lower margin_filter_n, higher accepted-bin permissiveness. |
Raise window_s, margin_filter_n, freq_medfilt_n, and min_bins; lower gamma_alpha. |
| Residual branch | residual_band_hz, z_on, z_off, res_on_n, res_min_growth_db, sigma0_floor, regime_hops |
Quiet-band hazard detection b_res when command excitation does not directly observe the dangerous band. |
Lower z_on, lower res_on_n, lower res_min_growth_db, widen hazard band only around real modes. |
Raise z_on, res_on_n, sigma0_floor; narrow residual_band_hz away from command harmonics. |
| Fast quick-dip | fast_st_nu, fast_st_h, fast_babs_offset, fast_burst_nu, fast_burst_h, fast_ring_n, fast_burst_bands |
Immediate trips for sudden FRF collapse or quiet-band burst: trip_reason 1 or 2, decision = 4. |
Lower fast_st_h, lower fast_burst_h, lower nu values, raise fast_babs_offset. |
Raise CUSUM thresholds, raise fast_ring_n, narrow fast_burst_bands, raise spread floors. |
| Authority drop | target, down_deadband, down_confirm_n, down_power, down_rate, down_settle_s, sev_frac, sev_down_rate, trip_drop, trip_power |
How b_osi and fast trips reduce auth. |
Raise target, raise down_rate, raise down_power, raise sev_frac, lower trip_drop. |
Lower target, raise down_confirm_n, widen down_deadband, raise down_settle_s. |
| Authority recovery | up_deadband, up_hold_s, up_rate, up_rate_blind, up_prop, min_step, pred_guard, latch_relax, latch_decay_tau_s |
How fast auth returns after margin is healthy. |
Lower up_hold_s, lower up_deadband, raise up_rate, raise up_prop, lower pred_guard. |
Raise up_hold_s, raise up_deadband, lower recovery rates, raise pred_guard, lower latch_relax, raise latch_decay_tau_s. |
| Speedgoat fit | fable_pred_enable, step_s, hop_s, band_hz, alpha_grid, fast_burst_bands |
CPU/TET budget and runtime latency. | Keep defaults for highest fidelity and fastest detection if TET permits. | Disable prediction first, then raise step_s or hop_s, narrow band_hz, reduce burst bands. |