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.

Current setupmain_ColumnSetup.m calls prepare_fable_runtime
Runtime blockfable_osi_runtime, scalar sample I/O, fixed-size arrays
Base ratefs = 2048 Hz, dt = 1/fs
Output folderresearch/osi_parameter_tuning

Source Map

FileRoleImportant 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.
Legacy branch-band fields: 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 fieldDefinitionBehavior controlled
projectFolderPath to main. Used to load saved exp_tf files through project helpers.File resolution only.
dtBase sample period in seconds. Current code uses dt = 1/2048.All window sizes and runtime step sizes.
hs.exp_tf_fileSaved 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_ncfTop-level target margin. In Fable it becomes cfg.threshold and prm.target.Main safety/performance setpoint. Higher is more conservative.
hs.osi_gain_minAuthority floor. Becomes prm.a_min.Deepest authority shed allowed.
hs.osi_gain_initialStartup and shadow-mode authority. Becomes prm.a_init.Initial product gain at Apply OSI gain.
hs.fable_osi_overrideStruct whose fields override cfg from fable_osi('config', ...).Estimator branch tuning: ST, residual, fast quick-dip, calibration, prediction grid.
hs.fable_auth_overrideStruct whose fields override prm from fable_auth('params', ...).Authority behavior: shed, recovery, trips, latch, commit gate.
hs.fable_pred_enableOptional 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)

ArgumentDefinition
ddNumerical command displacement sample in mm. This is the loop command used as the OSI input.
dmMeasured actuator displacement sample in mm. This is the OSI output.
enEnable 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.
fblsScalar OSI config vector. Index map is in prepare_fable_runtime and unpacked in unpackConfig.
fblwSlow Hann window, length segment_n.
fblbinsSlow-bin table: [freq_hz, fft_bin, keep, res_keep, nominal_curve].
fblfwFast Hann window, length fast_segment_n.
fblfbinsFast-bin table: [freq_hz, fft_bin, keep, cell_lo, cell_hi, band_id].
fblagAuthority-prediction relative gain grid alpha_grid.
fblaAuthority-law parameter vector. Index map is in prepare_fable_runtime and consumed by fableAuthStep.

Runtime outputs

OutputDefinitionLog meaning
authAuthority factor applied at the Apply OSI gain Product.Column auth. Lower means less loop authority.
b_osiSelected 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_stSlow coherent ST branch margin.Evidence from bins driven by dd with enough coherence and input power.
b_resSlow residual/quiet-band branch margin.Evidence from output power growth in undriven hazard bands.
b_fastFast short-memory ST margin.Quick-dip / sudden collapse indicator.
trip_reason0 none, 1 quiet-band burst trip, 2 fast FRF-collapse trip.Why immediate authority shed was triggered.
valid1 when b_osi is real post-warm-up evidence, 0 otherwise.Do not treat NaN/warm-up as a real safety margin.
decision0 hold, 1 down, 2 severe down, 3 up, 4 fast trip.Authority-law state machine output.

Core Equations

fs = 1/dt
segment_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_leak
quiet = 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 / baseline
normq = ratio / max(median(ratio(quiet)), eps)
z = (log(max(normq, eps)) - mu0) / sigma0
growth = 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_offset
cus_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*b
severe = b < sev_frac*target
low = min(b, b_filt) < target - down_deadband
a_pl = a_cont * (max(b_size, 0.02)/target)^down_power
a_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.

ParameterDefaultDefinitionTuning 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_s1.0Hann segment length for slow spectra.Keep near 1 s for 1 Hz resolution. Shorter weakens margin frequency resolution.
hop_s0.25Slow spectral refresh cadence. Must be compatible with step_s.Larger is cheaper and smoother but slower; smaller is faster but heavier.
step_s0.125Runtime OSI step cadence and fast path cadence.Larger lowers Speedgoat work; smaller improves quick-dip reaction but costs TET.
window_s5.0Slow ring memory. Produces n_segment median-aggregated segments.Longer gives stable margins; shorter follows changes faster but can false dip.
gamma_alpha0.01False-pass probability used to derive gamma_gate.Lower is stricter, accepting fewer coherent bins.
input_power_range_db35Bins this far below the in-band input peak are considered unexcited.Lower accepts only stronger command bins; higher accepts weaker bins.
sidelobe_db25Rejects bins that look like Hann leakage from a nearby stronger bin.Raise to be stricter about leakage; lower to keep more adjacent bins.
min_bins5Minimum excited slow bins required for b_st.Raise to reduce false ST decisions; lower to allow sparse excitation.
freq_medfilt_n3Median filter width across frequency bins.Raise to ignore single-bin dips; keep odd because runtime median assumes odd centered windows.
margin_filter_n3Temporal 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_alpha0.2EMA weight for b_slow_filt, used by fast path direction gate.Lower makes fast-trip reference steadier; higher follows level changes faster.
warm_updates4Number of slow updates before margins are reported.Raise to avoid startup artifacts; lower for earlier evidence.
cap1/sqrt(2)Mathematical maximum of the chordal margin.Not a normal tuning knob.
thresholdtarget_outer_ncfDetection threshold and fast-trip absolute level.Higher is more conservative; must be reachable by the healthy full-authority loop.
alpha_gridlogspace(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_floor1e-3Floor 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.

ParameterDefaultDefinitionTuning 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_quiet0.15Maximum raw coherence for a bin to count as quiet.Lower is stricter quiet selection; higher allows more bins into residual evidence.
residual_floor0.03Minimum fraction in res = Syy*max(1 - gamma2, residual_floor).Prevents residual power from going to zero under high coherence.
cal_skip_s10Startup blackout before accepting residual calibration windows.Raise if startup transients poison baseline.
cal_windows80Accepted slow-hop windows needed for full calibration.More gives stronger baseline; fewer calibrates faster.
cal_min_windows24Minimum accepted windows if timeout occurs.Lower calibrates under difficult data but weakens statistics.
cal_timeout_hops600Slow-hop attempts before timeout path can accept cal_min_windows.Lower allows earlier readiness after many rejects.
cal_reject_factor4Rejects 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_rejects12Consecutive rejects that restart calibration collection.Lower recovers faster from a bad initial reference.
z_on4.0Z-score threshold to engage residual branch.Lower detects earlier but risks false engagement; raise for fewer false alarms.
z_off2.0Z-score threshold below which engagement decays.Controls hysteresis. Lower holds residual engagement longer.
res_on_n4Consecutive slow hops above z_on needed to engage.Lower reacts faster; higher needs sustained evidence.
res_hold_s5Time 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_db3Absolute growth required in addition to z_on.Raise to ignore small quiet-band changes.
res_match_hz3Frequency persistence tolerance for the residual peak.Lower requires same-bin persistence; higher tolerates drifting mode frequency.
sigma0_floor0.15Floor on calibrated log-ratio spread.Raise to desensitize residual z-scores globally.
bl_adapt_tau_s100Time constant for healthy quiet-band baseline drift.Lower tracks benign drift faster but risks absorbing real degradation.
bl_adapt_max_db3Hard baseline adaptation cap around original baseline.Raise only if benign drift exceeds 3 dB; too high can hide damage.
regime_hops8Sustained 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.

ParameterDefaultDefinitionTuning effect
fast_segment_s0.25Fast 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_n3Number of fast segments in the fast median ring.Raise for smoother b_fast; lower for faster quick-dip sensitivity.
fast_min_bins3Minimum fast bins needed for fast ST margin.Raise to avoid trips from sparse evidence.
fast_st_nu1.25CUSUM drift for FRF-change statistic.Lower accumulates evidence faster; higher reduces false trips.
fast_st_h4.5CUSUM trip threshold for FRF-change statistic.Main fast ST sensitivity knob. Lower means earlier trips.
fast_babs_offset0.10Fast 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_frac0.02Relative 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_lo0.25Newest 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_hi4.0Newest command power must be below this multiple of its EMA.Lower rejects command bursts more aggressively.
fast_pin_alpha0.04EMA 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_nu1.0CUSUM drift for quiet-band burst z-scores.Lower detects bursts faster; higher calms the detector.
fast_burst_h6.0CUSUM trip threshold for quiet-band bursts.Lower trips sooner; higher requires stronger sustained burst evidence.
fast_sig_floor0.20Floor on calibrated log burst-power spread.Raise to desensitize all burst bands.
fast_d_sig_floor0.30Floor on calibrated log FRF-change spread.Raise to desensitize the fast ST CUSUM.

Authority-Law Parameters

These parameters are flattened into fbla. They control how the measured OSI behavior is converted into the gain factor auth that multiplies dc.

ParameterDefaultDefinitionTuning effect
target0.55, overridden by target_outer_ncfMargin level the authority law regulates onto.Primary safety/performance knob. Higher sheds earlier and recovers later.
a_min0.08Authority floor.Raise to preserve performance; lower to allow deeper emergency detuning.
a_max1.00Authority ceiling.Usually keep 1.0.
a_init1.00Startup and shadow-mode authority.Set lower only for intentionally detuned startup tests.
dt_updatecfg.step_sAuthority update cadence.Must match OSI runtime step cadence.
b_filt_tau_s0.4Time constant for margin EMA.Raise for smoother authority; lower for faster response.
down_deadband0.01Deficit begins below target - down_deadband.Widen to ignore tiny target grazes; narrow for tighter regulation.
down_confirm_n2Consecutive low updates before non-severe shed.Lower sheds sooner; higher rejects noise.
down_power1.5Exponent in a*(b/target)^down_power.Higher makes each shed deeper.
down_rate2.0Max confirmed shed rate in authority units per second.Raise to catch margin drops faster; lower for smoother authority.
down_settle_s1.25Hold time before resizing a shed from similar evidence.Lower re-sheds faster; higher avoids compounding a stale margin reading.
re_shed_delta0.02Fresh lower margin drop that bypasses down_settle_s.Lower makes continued decline resize sooner.
sev_frac0.60Raw margin below sev_frac*target is severe.Raise to treat more dips as emergencies; lower reserves severe path for deeper collapses.
sev_down_rate8.0Emergency shed speed.Keep high for crash-catching; lower only to reduce abrupt commands.
up_deadband0.02Recovery starts only above target + up_deadband.Raise to stop target-hugging oscillation; lower for faster recovery.
up_hold_s1.5Healthy dwell time before recovery.Raise for caution; lower to reclaim authority faster.
up_rate0.08Recovery rate when coherent ST evidence is valid.Raise for faster recovery under measured margin evidence.
up_rate_blind0.02Recovery rate without coherent input.Keep lower than up_rate; this is probe-and-verify recovery.
up_prop3.0Recovery boost from surplus margin.Raise to sprint when margin is comfortably high.
min_step0.02Commit gate from internal a_cont to applied auth.Raise for fewer, larger authority moves; lower for smoother continuous authority.
use_pred1Uses pred_margin to bound sheds and cap recovery.Set 0 when prediction grid is disabled for runtime budget.
pred_guard0.03Predicted margin must exceed target + pred_guard to count safe.Raise if prediction is optimistic; lower to recover more aggressively.
pred_floor_frac0.90Shed floor as fraction of predicted-safe authority.Lower allows more conservative shed below predicted boundary.
trip_drop0.60Multiplicative drop on fast trips.Lower is more aggressive. Burst trips may compound while evidence persists.
trip_power1.5Fast ST trip sizing exponent using b_fast/target.Higher makes low b_fast produce deeper immediate drops.
trip_cool_s5.0Cooldown after trip during which recovery is blocked and trip re-arms.Raise for caution after quick-dip events.
trip_undo_s2.5If regime recalibration follows a fast trip within this time, undo the trip.Raise to tolerate phase-change false trips; lower to keep trips latched.
self_move_gate_s1.5Authority must be steady this long before fast ST trip is honored.Prevents self-trip. Raise if authority motion still triggers fast ST.
self_move_frac0.02Relative committed authority move that resets self-move age.Lower is stricter about considering authority steady.
latch_relax1.15Post-event recovery ceiling relative to post-shed authority.Lower keeps recovery more latched after hard events.
latch_decay_tau_s1Time constant for forgetting the latched ceiling.Raise for slower post-event recovery; lower for faster recovery after healing.

Speedgoat Runtime Parameters

These are mostly scheduling and flattening parameters. They control whether the algorithm fits inside the 2048 Hz real-time budget.

Runtime itemDefinitionTuning or failure mode
P_PUB = 56Publish 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_enableControls whether the prediction grid runs.First TET reduction knob. Set 0 to skip prediction; authority then uses power-law regulation alone.
step_sControls OSI step cadence and fast path cadence.If target overruns, raising to 0.25 halves fast-path rate.
hop_sControls slow path refresh cadence.If target overruns, raising to 0.5 halves slow-pipeline rate.
band_hzFrequency span stored in fblbins and fblfbins.Narrow to reduce bin count and median/prediction work.
segment_sSlow FFT length.Do not shrink below 1 s unless accepting worse frequency resolution.
freq_medfilt_nRuntime assumes odd centered medians.Keep odd; prepare_fable_runtime asserts this.
enRuntime enable code.Current model uses direct enable wiring; the OSI keeps evaluating during command pause.
Speedgoat overload response order from the runtime header: 1. 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.