matlab-identify-linear-system

# Linear Model Identification
  Estimate a linear dynamic model from measurement data using MATLAB System Identification Toolbox. This skill selects the right model type, determines model order, estimates parameters, and validates results — following the methodology a System Identification Toolbox expert would use.

## When to Use
- Identify a transfer function, state-space, or process model from I/O data
- Determine model order from measurement data
- Fit a parametric model for simulation, prediction, or control design
- Convert frequency response data (FRD) to a parametric model
- Compare model structures (ARX vs state-space vs transfer function)  
- Determine frequency response from time-domain data
- Determine a plant model for PID tuning or control design
- Obtain a data-driven linear model when linearization of a Simulink model is not possible or practical
- Tune parameters of a physics-based model (grey-box) using data
- Compare multiple models to determine which best fits the data
- Simulate or predict system response using the identified model
- Perform subspace identification for high-order systems or MIMO systems, or use Eigenvalue Realization Algorithm (ERA) 
- Extract modal parameters (natural frequencies, damping ratios, mode shapes) from frequency response
- Compare model structures (ARX vs state-space vs transfer function)
- Study the possibility of feedback in data by analyzing the correlation between input and output signals
- Study persistence of excitation in the input signals to ensure that the data is informative enough for model identification

## When NOT to Use
- When the system is inherently nonlinear and a linear model is not appropriate
- When the available data is insufficient or of poor quality for reliable model identification
- When the primary goal is to identify a nonlinear model (e.g., neural state-space, NLARX, Hammerstein-Wiener)  
- When estimating the parameters of a Simulink model using experimental data; use Simulink Design Optimization Toolbox instead
- When designing a controller; use Control System Toolbox skills after identifying the plant
- Signal processing (filtering, spectral analysis without model fitting) — use signal processing skills


## Execution Strategy

**Write a single end-to-end MATLAB script and run it.** Do NOT step through phases one tool call at a time. The script should:
1. Create/load data + split into estimation/validation
2. Estimate delay, select structure, estimate model(s)
3. Validate on held-out data by simulation
4. Print results

Only break into multiple steps if the first script fails or produces poor results (fit < 70%).

**Critical rules for every script (MANDATORY — violating any of these is a bug):**
* `InteractiveOrderSelection=false` when using order vectors — this is a HIDDEN property (not visible in disp() or tab-complete) on BOTH ssestOptions AND n4sidOptions. It MUST be set explicitly or a GUI popup HALTS execution
* `EstimateCovariance=false` during ANY search loop (order scan, delay scan) — covariance for discarded models wastes time
* `Focus='simulation'` for simulation/control use on `ssestOptions`, `n4sidOptions`, `procestOptions` (NOT available on `tfestOptions` — tfest has no Focus)
* Multi-model compare returns CELL: `[~, fits] = compare(zv, m1, m2); fits{1}, fits{2}` — ALWAYS pass 2+ models to ONE compare() call, NEVER call compare() separately per model
* `data.InterSample = 'foh'` BEFORE CT estimation if input is smooth analog
* For multi-input InterSample: use column cell `{'zoh'; 'foh'}` (NOT row cell)
* **Delay-first**: ALWAYS call `delayest` or inspect impulse response BEFORE any model estimation (even for MIMO, even when delay seems small)
* **Hedge delays**: NEVER trust a single delay estimate — always try nk AND nk±1, compare fits, pick best
* **Order range**: When selecting order, use a RANGE (vector) not a single integer — `ssest(ze, 2:8, opt)` not `ssest(ze, 4, opt)`

## Arguments

The user provides: $ARGUMENTS

Parse:

* **project_name** (optional): name of a project under `projects/` that has a `SPEC.md`
* **data_source** (optional): path to a `.mat` file, variable name in workspace, or inline description of the data

If neither is provided, ask the user to specify a data source or describe the identification problem.

---

## Design Principles

1. **Start simple, add complexity only when data justifies it.** Try order 2-4 before 10-15.
2. **Delay first.** A wrong delay cannot be fixed by higher order — it's catastrophic.
3. **Set Focus correctly.** The #1 missed option. Default 'prediction' is sometimes wrong for simulation use.
4. **Always hold out validation data.** Never report training fit as performance.
5. **Regularization > high order.** A regularized ARX(30) often outperforms unregularized ARX(5). Use `arxRegul`, or `ssregest`.
6. **State-space is the default.** When unsure, `ssest` handles MIMO, CT/DT, needs only order n.
7. **Compare 2-3 structures.** The first model is rarely the best.
8. **Check residuals.** A high fit with correlated residuals means the model is missing dynamics.
9. **Know when to stop.** >90% fit with white residuals on validation data is success.

---

## Fast Path — Use When Problem Is Clear

If the problem maps directly to one of these patterns, write a single script immediately:

**Step/impulse response → process model** (do NOT split single-transient data):
```matlab
% Step data is one transient — splitting creates IC discontinuity. Use full data.
opt = procestOptions('Focus', 'simulation');
m1 = procest(data, "P1D", opt); m2 = procest(data, "P2D", opt);
[~, fits] = compare(data, m1, m2); fprintf('P1D: %.1f%%, P2D: %.1f%%\n', fits{:});
fprintf('K=%.2f, Tp=%.1f, Td=%.1f\n', m1.Kp, m1.Tp1, m1.Td);
```

**SISO time-domain → transfer function:**
```matlab
ze = data(1:floor(end*0.7)); zv = data(floor(end*0.7)+1:end);
nk = delayest(ze);
% Hedge delay: try nk-1, nk, nk+1
delays = max(1, nk + (-1:1));
opt = ssestOptions('Focus', 'simulation', Interactiv