path: root/scripts/README.md

# Scripts

Status index (paper-grade commands live in `notes/40_reproduction_manifest.md`;
the recipes further down this file cover the static-geometry scripts).

**Core experiment scripts (paper-grade):**

| script | what it validates | note |
|---|---|---|
| `capacity_empirical_validation.py` | Beta law, tails, multilayer product | 02 |
| `multilayer_capacity_distribution.py` | surprisal Exp(1) / Gamma(L,1) | 02 |
| `minimax_initialization.py`, `initialization_distribution_matching.py` | minimax 1/D + coverage per scheme | 02 |
| `functional_capacity_overlap.py` | hard rank loss + kd/P overlap | 02 |
| `downstream_capacity_sweep.py` | BP/FA sweep engine (dense ramp run, teacher run) + shared MLP/grad infra | 22, 39 |
| `closed_form_soft_ramp.py` | closed-form gap law vs dense ramp (matched data/init + init band) | 34, 37 |
| `actual_fa_initial_operator_moments.py` | T3: E_B[e0] = hidden speed share | 29 |
| `actual_fa_initial_erosion_distribution.py` | P3: exact Gaussian e0 (real-backward sampler) | 32, 37 |
| `compressed_operator_predictor.py` + `plot_compressed_operator_results.py` | early-velocity estimator, 256-traj set | 15 |
| `summarize_operator_stress_grid.py` + `plot_operator_overlap_grid.py` | estimator stress grid | 16, 17 |
| `finite_time_kernel_diagnostic.py` | oracle time-varying K(t) vs fixed K(0) | 13 |
| `real_data_validation.py` | MNIST: T3 + estimator (has `--self-test`) | 38 |
| `plot_teacher_test_gap.py` | teacher train-vs-test gap figure | 39 |
| `feedback_rules.py`, `test_feedback_rules.py` | shared arbitrary-depth BP/FA/DFA implementation + numerical checks | 43 |
| `aaai_depth_experiments.py` | FA/DFA initialization depth calibration + FA finite-time depth/width grid | 43 |
| `parameter_matched_depth_control.py` | equal-parameter-count finite-time depth control for the supplement | 43 |
| `learning_rate_compensation.py` | same-rate, initialization-compensated, and independently tuned controls | 43 |
| `cnn_initialization_validation.py` | FA/DFA initialization theorem on a cross-entropy CNN | 43 |
| `plot_aaai_main_figures.py` | two focused three-panel main figures | 43 |

**Diagnostics / negative results (kept for the record):**
`fa_tangent_kernel_capacity.py` (kernel capacity probe, note 07),
`early_kernel_predictors.py` (scalar predictors fail, note 14),
`fa_tangent_hierarchy_derivative_probe.py` (derivative extrapolation blows
up, note 31), `soft_erosion_theory_vs_empirical.py` (hard-k overpredicts,
note 25), `static_alignment_beta.py` + `capacity_scaling.py` (small static
demos subsumed by the large validation).

**Historical (bridge/ensemble era, superseded):**
`trajectory_mlp_fa.py`, `trajectory_ensemble.py`,
`trajectory_gap_distribution.py` (notes 02/08),
`plot_phase_transition*.py`, `plot_dense_phase_transition.py`,
`plot_capacity_transition_overlay.py` (kink-era visualizations, notes 19-22),
`plot_tangent_hierarchy_first_order_try.py` (note 31).

---

## Static Alignment Beta Law

Run:

```bash
python scripts/static_alignment_beta.py --rows 16 --cols 16 --samples 20000 --seed 7 --plot
```

This samples independent matrix pairs \(A,B\), computes:

\[
Q =
\frac{\langle A,B\rangle_F^2}{\|A\|_F^2\|B\|_F^2},
\]

and compares the empirical distribution with:

\[
\mathrm{Beta}\left(\frac12,\frac{D-1}{2}\right),
\qquad
D=\texttt{rows}\times\texttt{cols}.
\]

Outputs are written under `outputs/static_alignment_beta/`, which is ignored by Git.

## Capacity Scaling

Run:

```bash
python scripts/capacity_scaling.py --plot
```

This computes:

\[
C_l(q)
=
-\log\Pr(Q_l\ge q)
\]

for equal-width feedback blocks with \(D=n^2\), then sums over the number of feedback-aligned layers:

\[
C_{\mathrm{all}}=\sum_l C_l(q_l).
\]

The default run compares two regimes:

- `fixed`: \(q=0.01\), where \(C_{\mathrm{all}}\) grows like \(\Theta(Ln^2)\).
- `chance`: \(q=1/D\), where \(C_{\mathrm{all}}\) grows mostly with \(L\).

Outputs are written under `outputs/capacity_scaling/`.

## Large Empirical Capacity Validation

Run:

```bash
python scripts/capacity_empirical_validation.py --dimensions 64 128 256 512 1024 2048 4096 --samples 100000 --batch-size 2048 --seed 123 --plot
```

This uses rotational invariance to fix the target direction and sample random
feedback directions:

\[
Q=\frac{z_1^2}{\|z\|^2},
\qquad
z\sim \mathcal N(0,I_D).
\]

It validates:

- beta-law distribution calibration across dimensions;
- empirical tail probabilities for \(q=c/D\) and fixed \(q\);
- empirical capacity cost \(C(q)=-\log P(Q\ge q)\);
- multilayer product scaling for all-alignment events.

Outputs are written under `outputs/capacity_empirical_validation/`:

- `distribution_summary.csv`
- `capacity_tails.csv`
- `multilayer_capacity.csv`
- diagnostic plots when `--plot` is set.

## Multilayer Observed Capacity Distribution

Run:

```bash
python scripts/multilayer_capacity_distribution.py --dimensions 64 256 1024 4096 --layers 1 2 4 8 16 --samples 100000 --batch-size 8192 --seed 456 --plot
```

This validates the full null distribution of observed capacity surprisal:

\[
S_l=-\log P(Q_l'\ge Q_l).
\]

Theory predicts:

\[
S_l\sim \mathrm{Exp}(1),
\qquad
\sum_{l=1}^L S_l\sim \mathrm{Gamma}(L,1).
\]

The script samples random direction cosines through the exact chi-square
representation \(Q=X/(X+Y)\), with \(X\sim\chi^2_1\) and
\(Y\sim\chi^2_{D-1}\). Outputs are written under
`outputs/multilayer_capacity_distribution/`.

## Minimax Initialization Bound

Run:

```bash
python scripts/minimax_initialization.py --dimension 32 --feedback-samples 20000 --target-samples 10000 --seed 11 --subspace-dim 4 --plot
```

This estimates the feedback second-moment matrix:

\[
M_\mu=\mathbb E_\mu[\hat b\hat b^\top]
\]

for several initialization distributions. The worst-case expected squared alignment is:

\[
\inf_{\|a\|=1}
\mathbb E_\mu[(a^\top \hat b)^2]
=
\lambda_{\min}(M_\mu).
\]

The prior-free minimax theorem says:

\[
\sup_\mu \lambda_{\min}(M_\mu)=\frac1D,
\]

with equality for isotropic feedback. Outputs are written under `outputs/minimax_initialization/`.

## Initialization Coverage Distribution Matching

Run:

```bash
python scripts/initialization_distribution_matching.py --dimension 128 --target-samples 100000 --feedback-samples 100000 --batch-size 8192 --seed 2026 --subspace-dim 8 --anisotropy 64 --plot
```

For an initialization distribution \(\mu\), define:

\[
M_\mu=\mathbb E[\hat b\hat b^\top].
\]

For a random target direction \(a\), theory predicts the coverage distribution:

\[
A(a)=a^\top M_\mu a
=
\frac{\sum_i \lambda_i G_i}{\sum_i G_i},
\qquad
G_i\sim\chi^2_1,
\]

where \(\lambda_i\) are eigenvalues of \(M_\mu\). The script compares this
population-predicted distribution with the distribution induced by an empirical
second-moment estimate from sampled feedback directions.

Outputs are written under `outputs/initialization_distribution_matching/`.

## Functional Capacity Overlap

Run:

```bash
python scripts/functional_capacity_overlap.py --parameters 96 --task-rank 24 --constraint-ranks 0 24 48 72 84 96 --trials 100 --seed 5 --plot
```

This samples a task-sensitive subspace \(S\) of dimension \(d\) and an alignment
constraint subspace \(E\) of dimension \(k\) inside \(\mathbb R^P\). It validates:

\[
\Delta d_{\mathrm{hard}}
=
\max(0,k-(P-d))
\]

and:

\[
\mathbb E[\operatorname{tr}(P_E P_S)]
=
\frac{kd}{P}.
\]

Outputs are written under `outputs/functional_capacity_overlap/`.

## Synthetic MLP FA/BP Trajectories

Run:

```bash
python scripts/trajectory_mlp_fa.py --samples 128 --hidden-widths 24 24 --steps 80 --lr 0.02 --eval-every 10 --feedback-runs 3 --data-seed 3 --init-seed 4 --feedback-seed-start 50 --plot
```

This trains one BP baseline and several FA runs from the same initial weights on
a synthetic regression task. At each checkpoint, the script records:

- training loss;
- full-model cosine between the BP gradient and the FA surrogate gradient at the FA weights;
- hidden-layer-only cosine between the BP and FA gradients, excluding the output layer where gradients are identical;
- layerwise \(Q_l=\cos^2(W_{l+1}^{\top},B_l)\).

Outputs are written under `outputs/trajectory_mlp_fa/`:

- `summary.csv`
- `trajectories.csv`
- `layer_metrics.csv`
- diagnostic plots when `--plot` is set.

## Synthetic Trajectory Ensemble

Run:

```bash
python scripts/trajectory_ensemble.py --architectures 16,16 24,24 32,32 48,48 24,24,24 --samples 256 --steps 200 --lr 0.02 --eval-every 20 --feedback-runs 40 --data-seed 20 --init-seed 30 --feedback-seed-start 1000 --plot
```

This runs one BP baseline and many FA feedback seeds for each architecture,
then aggregates:

- final FA/BP loss gap;
- full and hidden-only gradient cosine;
- initial and final \(Q_l\) means;
- initial and final log-volume capacity cost;
- within-architecture and pooled correlations.

Outputs are written under `outputs/trajectory_ensemble/`:

- `run_summary.csv`
- `architecture_summary.csv`
- `correlations.csv`
- `trajectories.csv`
- diagnostic plots when `--plot` is set.

## Trajectory Gap Distribution Bridge

Run:

```bash
python scripts/trajectory_gap_distribution.py --hidden-widths 16 16 --samples 128 --steps 60 --lr 0.02 --feedback-runs 1000 --data-seed 7 --init-seed 8 --feedback-seed-start 10000 --outdir outputs/trajectory_gap_distribution/h16x16_1000 --plot
```

This compares the empirical FA/BP final loss-gap distribution with a BP-path
bridge predictor. For each feedback seed \(B\), the bridge integrates:

\[
\delta_T(B)
=
-\eta\sum_{t<T}
\left[
g_{\mathrm{FA}}(\theta_t^{\mathrm{BP}};B)
-
g_{\mathrm{BP}}(\theta_t^{\mathrm{BP}})
\right],
\]

then predicts:

\[
\widehat{\Delta L}_T(B)
=
L(\theta_T^{\mathrm{BP}}+\delta_T(B))
-
L(\theta_T^{\mathrm{BP}}).
\]

Outputs include raw distribution comparisons and standardized or moment-matched
shape diagnostics under `outputs/trajectory_gap_distribution/`.