# MATLAB Working Style

This file gives an AI coworker the MATLAB habits expected in this project.
It supplements the technical reference PDFs; it does not replace them.

## Arrays Before Scalar Loops

Prefer MATLAB's array model when the operation is naturally array-oriented.

```matlab
activeRows = A(:, 2) == 1;
activeConfig = A(activeRows, :);
```

Prefer that form over a loop that examines and copies one row at a time.

Use a logical mask directly when only selection is needed:

```matlab
selected = values > threshold;
filteredValues = values(selected);
```

Use `find(selected)` only when the numeric positions themselves are required.

Before writing a scalar loop, consider:

- Logical indexing and colon indexing
- Implicit expansion
- `reshape`, `permute`, and dimension-aware operations
- `sum`, `mean`, `diff`, `any`, `all`, `min`, and `max`
- Matrix multiplication or element-wise arithmetic

## Loops That Express the Algorithm

Vectorization is not an absolute rule. Keep a loop when each iteration has
scientific meaning or depends on evolving state.

Examples include:

- Moving a tapered window through a signal for a manual STFT
- Iterative optimization or convergence
- Instrument commands that must be ordered
- Streaming acquisition and state machines

Preallocate loop outputs:

```matlab
tf = zeros(numberOfFrequencies, numberOfWindows);
```

## Dimensions and Operators

- State whether signals are rows or columns.
- Check the dimension along which `fft`, `mean`, filtering, or fitting acts.
- Use `.'` for transpose without complex conjugation.
- Use `'` deliberately when a Hermitian transpose is required.
- Distinguish matrix multiplication `*` from element-wise multiplication `.*`.
- Distinguish matrix powers from element-wise powers.
- Prefer `A\b` for solving a linear system; avoid explicitly computing an
  inverse merely to solve equations.

## Fourier and Signal Analysis

Do not treat an FFT call as a complete analysis. Make these choices explicit:

- Sampling rate and time-vector convention
- Transform dimension
- Frequency vector
- One-sided or two-sided representation
- Coefficient, amplitude, power, or PSD scaling
- DC and Nyquist handling
- Window type and length
- Stationarity assumptions
- Time-frequency resolution tradeoff
- Phase convention and unwrapping
- Edge effects and causal versus zero-phase filtering

When useful, show both:

1. A manual or educational implementation that exposes the algorithm.
2. The current MATLAB built-in that performs the production operation.

## Demonstration Code

- Keep connection settings and user configuration near the top.
- Keep the main script readable from top to bottom.
- Use local functions for repeated or conceptually separate work.
- Comment instrument-specific behavior and design intent, not obvious syntax.
- Write settings, read them back, compare, then enable outputs.
- Distinguish stored instrument settings from analog measurements.
- Preserve complete native errors after releasing communication resources.

## Explanations

Assume substantial self-taught MATLAB experience. Explain unfamiliar syntax,
array orientation, numerical conventions, instrument behavior, and important
tradeoffs. Do not turn every line into a beginner tutorial.

When a reference-note method materially affects the solution, name the source
document and page so the connection to earlier learning is visible.
