Codebase review

Independent audit of the ColumnSetup MATLAB, Simulink, identification, control, and FEM workflows. Findings distinguish verified code behavior from hypotheses and risk inferences.

Offline tests8 passing
Priority findings6 open · 4 closed
Physical runNot performed

Implemented revisions

  • Corrected one-sided FFT normalization for DC, Nyquist, odd-length signals, and frequency limiting; added regression tests.
  • Replaced the hard-coded stability threshold with the first unstable stiffness-sweep value, reused computed margins, and removed explicit matrix inverses.
  • Prevented infeasible destabilizing-controller results from being cached, returned, or saved as usable controllers.
  • Standardized specimen parameters and physical calculations in kg, N·s/m, and N/m while retaining raw experimental displacement in mm and acceleration in g for storage and visualization.
  • Removed the implicit caller-workspace override from load_saved_result_file. Its API now verifies an explicit file against the requested result category, while visualization wrappers retain the legacy ambient bridge.
  • Added a guard for the common case where no new Speedgoat file-log row appears, added seconds to result filenames, and refused overwrites.
  • Made the W8x28 experimental and frame definitions use the same exact section moment of inertia.
  • Added MATLAB tests for FFT scaling, saved-result category enforcement, and specimen-unit conversion.
  • Removed the scale-equivalent degree of freedom from closed-loop identification by fixing a1b0 = 1. Existing Kp and Ki names now hold the identifiable normalized products, with the model polynomial and output descriptions unchanged.
  • Corrected the active workspace path in AGENTS.md and ignored SAP .tlog scratch files.
  • Documented that controller-tuning analyses are research-only and their saved controller results do not affect simulations.
  • Added an official noise-whitened TLS workflow with displacement-derived acceleration, approximately non-overlapping KF assimilation, stored estimator configuration, and synthetic unit-invariance and coverage tests.

High-priority findings

Resolved1. Parametric identification had a scale-equivalent degree of freedom

The optimizer now fixes a1b0 = 1 and estimates the identifiable normalized values through the existing Kp and Ki fields. The transfer-function equations and output descriptions remain unchanged. A synthetic regression demonstrates the original scaling invariance, verifies a1b0 == 1, recovers both normalized values within 1e-6 relative tolerance, and matches the frequency response within 1e-8 relative error. Issue #1 is closed.

Confirmed2. “Digital” control is continuous-time

pidtune, feedback, and the margin calculations omit sample time, zero-order hold, computation and DAQ delay, quantization, rate limits, and saturation. The results are continuous outer-loop results, not sampled-data guarantees.

Intentional3. Tuning analyses are disconnected from the experiment

The tuning scripts are research-only analyses. Their saved controller MAT files are not loaded by main_ColumnSetup.m and do not affect the Simulink simulations. Issue #3 was closed as not planned.

Resolved4. TSE/TLS estimation is normalized and its uncertainty is calibrated

The official offline and online-style paths now share a noise-whitened TLS estimator, derive acceleration consistently from displacement, and assimilate approximately non-overlapping windows. The saved configuration records the estimator settings, while synthetic tests verify unit invariance, parameter recovery, and the stated empirical coverage target. Issue #4 is closed.

Accepted5. Reference/hybrid equivalence is only first-mode exact

Story height zeros the first-mode interface moment. Modes 2 and 3 move the inflection point 10.01 in and 17.15 in below the interface, respectively. A rotational-interface model reproduced the reference stiffness to 3.99 × 10−16 relative error and returned J4–J7 = 0.00% for every record, confirming that the released higher-mode interface moment causes the errors below within the linear FEM.

EarthquakeJ4J5J6J7
El Centro0.46%0.37%0.11%0.17%
Northridge0.68%0.76%0.17%0.26%
Kobe0.82%0.92%0.21%0.31%
Loma Prieta1.31%1.23%0.32%0.49%
Chi-Chi0.14%0.16%0.03%0.05%
Imperial Valley0.47%0.32%0.12%0.19%
Landers0.58%0.66%0.15%0.22%
Tabas3.46%3.99%0.90%1.34%
San Fernando0.28%0.25%0.08%0.11%
Tohoku6.09%4.57%1.58%2.34%

AcceptedThese bounded errors are accepted for the translation-only hybrid interface. Issue #5 is closed.

Confirmed6. Black-box fitting modifies stability evidence

The fit inserts an exact synthetic DC point, reflects unstable poles into the left half-plane, selects model order using in-sample error, and derives margins from H/(1-H).

Risk inferenceThese operations can make stability appear stronger than the raw fit supports. Use constrained stable identification, held-out validation, and uncertainty intervals.

Confirmed7. Experimental provenance is incomplete

The row-count guard catches the common no-new-row case but cannot prove run identity when retention holds table height constant or ordering changes. Saved results omit calibration, channel mapping, signal configuration, controller profile, target run ID, repository state, and model checksum.

Confirmed8. Other optimization paths can accept infeasible candidates

The general digital and settling-time optimizers choose the lowest returned objective without checking final constraints and solver status. Apply the feasible-candidate rule now used by the destabilizing optimizer.

Confirmed9. Partial online recomputation leaves inconsistent state

Recomputing one TLS/KF interval changes its terminal posterior, so later estimates must also be invalidated and propagated. Window and configuration changes can currently mix estimates created under different settings.

Contradictions and documentation drift

  • The FEM definition now presents specimen-specific story height in metres, distinguishes level mass in kg from derived weight in N, and stores reference/numerical FEM definitions together as saved_results/fem/fem_<specimen>.mat.
  • The reference plot draws fixed bases although the analyzed model uses finite base rotational springs.
  • The damage sweep lowers damping with stiffness to preserve damping ratio. This is a specific damage law, not a neutral stiffness-only sensitivity study.
  • AGENTS.md contains obsolete breakpoint lines, a missing helper directory, an infinite configured “full” run, conflicting physical-run approval rules, and R2020b-specific advice despite this audit running under R2025b.
  • The persisted directory name paarametric is misspelled throughout the workflow. Migrate with backward-compatible reads rather than renaming it in place.

Independent next steps

  1. Build a physics-consistent synthetic digital twin with known time-varying specimen parameters, actuator dynamics, controller, synchronized sensor noise, bias, saturation, and delay. Measure estimator bias, RMSE, interval coverage, detection delay, and false alarms.
  2. Quantify uncertainty in the normalized closed-loop fit using block bootstrap or profile likelihood, then propagate a model ensemble into stability margins.
  3. Create a sampled-data, multirate model with ZOH and a measured delay distribution. Evaluate robust stability over specimen, model, and delay uncertainty.
  4. Add an interface energy and passivity observer as an independent real-time safety channel for nonlinear or time-varying specimens.
  5. Quantify hybrid partition approximation with modal MAC, frequency and FRF errors, and record-level response errors. Compare translation-only with translation-plus-rotation or condensed dynamic impedance.
  6. Use constraint-aware experiment design—such as multisine or PRBS selected through Fisher information—within stroke, force, and velocity limits.
  7. Introduce a versioned MAT schema and experiment registry with content hashes and lineage from raw run to specimen, identified model, controller, and FEM. Separate offline CI from opt-in physical HIL verification.

Verification status

  • MATLAB static analysis reports no issues in changed MATLAB files.
  • Eight offline tests pass. They cover FFT scaling, saved-result category enforcement, specimen-unit conversion, and normalized closed-loop parameter identification—not Speedgoat identity, optimizer feasibility, or stability plots.
  • No physical Speedgoat run was performed.

Identification and controllers must be regenerated because existing parametric files used the inconsistent unit convention.