# simEigenmode

Runs a Verlet dynamics simulation of the packing in which a single selected
eigenmode is excited as the initial displacement, then checks the mode's
predicted frequency and attenuation against what the dynamics actually produce.
Builds neighbor lists once (periodic x/y), displaces the particles along the
selected eigenvector (amplitude = `P_target * 0.01`), integrates for ~500
box-crossings, and plots probe-particle `dx(t)`, `dy(t)`, a `|u(t)|` attenuation
fit (ln|u| vs t), and the FFT amplitude `|ũ(omega)|`. Saves the figure to
`data/junkyard/simEigenmode.png` and returns the eigen-frequency ratio
`omega_eig / omega_max`.

## Default Syntax

```matlab
strLoadPath = "path/to/results_2D_iso_N100_P0.1_Seed5_gamma_3.00e-03.mat"
simEigenmode(strLoadPath, scalModeFreq = 0.3)   % scalModeFreq: double, target omega
```

Loads the results file (packing + eigenvalues/eigenvectors), picks the mode
closest to the target frequency, simulates it, and reports how well the
eigenvalue prediction matches the dynamics.

## Options

Mode selection — exactly one must be non-zero:

- `opts.scalModeFreq` (double, default 0) — target frequency; the eigenmode
  whose imaginary part is closest to this value is excited.
- `opts.scalModeAtten` (double, default 0) — target attenuation; the eigenmode
  whose real part is closest to this value is excited.

Input format:

- `opts.loadPolyData` (logical, default false) — true: the file holds the
  `outData` struct from `processEigenModesDampedPara` (`eigenVectors`,
  `eigenValues`, `radii`, `positions`, `Lx`, `Ly`, `pressure`, `damping`,
  `springConstant` — cells). false: a `pack.m` results file with `packing`,
  `eigenvalues`, `eigenvectors`.

Simulation behavior:

- `opts.negDy` (logical, default false) — flips the y-DOF rows of the
  eigenvector before use. Needed for results from the old
  `matSpringDampMass` convention ([dx,-dy] ordering); compare with and without
  to identify which convention a results file uses.
- `opts.visSim` (logical, default false) — draw per-timestep
  displacement-vs-position plots during the run.
- `opts.fullSpectrum` (logical, default false) — store every particle's
  trajectory (N x Nt matrices) for post-processing.
- `opts.flagVarMass` (logical, default false) — mass proportional to
  `pi/4 * D^2` instead of unit mass.

## Examples

```matlab
% Excite the mode closest to omega = 0.3 in a pack.m results file
simEigenmode("data/eigenData/results_2D_iso_N100_P0.1_Seed5_gamma_3.00e-03.mat", ...
             scalModeFreq = 0.3);

% Same file, but with the old [dx,-dy] eigenvector convention
simEigenmode("data/eigenData/results_2D_iso_N100_P0.1_Seed5_gamma_1.00e-02.mat", ...
             scalModeFreq = 0.3, negDy = true);

% Select by attenuation (beta) instead of frequency
simEigenmode("data/eigenData/results_2D_iso_N100_P0.1_Seed5_gamma_1.00e-02.mat", ...
             scalModeAtten = -0.05);

% outData file (from processEigenModesDampedPara)
simEigenmode("data/junkyard/2D_eigenData_10by10_P0.100_damp0.010_K100_M1.mat", ...
             scalModeFreq = 0.1, loadPolyData = true);

% Large system, visualize the simulation as it runs
simEigenmode("data/eigenData/results_2D_iso_N16000_P0.1_Seed5_gamma_1.00e-03.mat", ...
             scalModeFreq = 0.02, negDy = true, visSim = true);
```