# plotModes

Plots the damped eigenmodes of every results file in a directory. Scans for
`results_2D_iso_N*_P*_Seed*_gamma_*.mat` and `results_3D_N*_P*_Width*_Seed*_gamma_*.mat`,
then draws attenuation vs. frequency (log-log) in a tiled layout: one column per
damping `gamma`, top row raw, bottom row with frequency normalized by
`sqrt(P)`. Color encodes pressure, marker encodes N. Reference `omega^2` and
`omega^(1/3)` scaling lines are drawn for comparison.

## Default Syntax

```matlab
resultsDir = "path/to/your/results"   % string, directory containing results_*.mat files
averageMass = 1;                       % double, average particle mass
plotModes(resultsDir, averageMass)
```

This scans the directory and plots every eigenmode spectrum it finds (2D + 3D).
X-axis is the reduced frequency `omega*sqrt(m)`, y-axis the reduced attenuation
`beta*sqrt(m) / (gamma/sqrt(m))`.

## Options

Pass a struct as a third argument. All fields are optional; "closest match"
selection is used — if a target value is not present in the files, the nearest
value that is present gets plotted.

```matlab
opts.argGamma       = [0.01 0.001];   % double vector, target gammas
opts.argPressure    = [0.1 0.02];     % double vector, target pressures
opts.argN           = [216 1000];     % double vector, target particle counts
opts.argSeed        = [1 3];          % double vector, target seeds
opts.scalPressure   = 0.25;           % double, multiply y by P^0.25 (0 or empty -> no scaling)
opts.flagCoordNumRow = true;          % logical, add a 3rd row whose y is divided by the
                                      %         packing's mean coordination number z-bar
plotModes(resultsDir, averageMass, opts)
```

- `argGamma` / `argPressure` / `argN` / `argSeed` — filter which files are
  plotted (closest match, not exact).
- `scalPressure` — scales the y-value by `P^scalPressure`; the axis label
  updates to show the exponent (0.25 renders as P^(1/4)).
- `flagCoordNumRow` — off by default. If the saved packing lacks
  `scalMeanCoordNum` it is recomputed from the saved positions exactly as
  `pack.m` does (wall contacts not counted).

## Examples

```matlab
averageMass = 1;

% Plot all results in a directory
plotModes('data/eigenData/', averageMass);

% Gamma/pressure selection + P^(1/4) scaling
opts.argGamma     = [0.01 0.001];
opts.argPressure  = [0.1 0.02];
opts.scalPressure = 0.25;
plotModes('data/eigenData/', averageMass, opts);

% Same, plus the coordination-number-normalized row
opts.flagCoordNumRow = true;
plotModes('data/eigenData/', averageMass, opts);
```