# Catnip FP8 outlier statistics

This directory is a self-contained, read-only study of the 576 tensorwise-FP8
Linear layers in the team's `baseline27FPS` project. The implementation source
of truth is `/workspace/week2-improved-fp8_scaled`; later-week code changes are
not adopted. Existing week4 activation observer bundles are reused only as
measurement inputs and are matched one-to-one against the week2 manifest.

## Main deliverable

- Chinese LaTeX report: [`report/main.pdf`](report/main.pdf), 21 A4 pages
- LaTeX source: [`report/main.tex`](report/main.tex)
- Machine-readable summary: [`data/processed/analysis_summary.json`](data/processed/analysis_summary.json)
- INT8 mechanism control: [`data/processed/int8_control_summary.json`](data/processed/int8_control_summary.json)
- Eleven figures, each in PDF and PNG: [`figures/`](figures/)

Key conclusion: weight outliers strongly increase nonzero-to-zero underflow
(Spearman rho 0.812), but tensor amax/p99.99 does not explain E4M3
energy-weighted relative L2 (rho -0.046). Real activation tails show materially
stronger relationships with local tensorwise error (rho 0.380) and rowwise MSE
gain (rho 0.442). These are reconstruction-level results, not end-to-end media
quality approval.

## Coverage

- 576 Linear weights, 48 blocks x 12 families
- 13,690,208,256 exact weight elements for FP8 errors/counterfactuals
- 63,360 real Streaming activation call records from two 20-second requests
- 4,000 family-stratified bootstrap replicates per reported correlation
- Ten scale multipliers from 1.0 through 0.0625
- Exact tensorwise, output-channel, dense-clipping, and sparse-residual weight
  error accounting; deterministic sampled uniform-INT8 mechanism control

Weight quantiles and the INT8 control use at most 262,144 evenly spaced samples
per layer. Activation amax is full-call exact; activation percentiles and the
tensorwise/rowwise quantization probes are bounded deterministic samples. See
the report's limitations section before using any layer ranking operationally.

## Reproduce

```bash
cd /workspace/catnip-fp8-outlier-statistics

/workspace/LTX/.venv/bin/python scripts/analyze_weight_outliers.py \
  --config config/experiment.json \
  --output-jsonl data/raw/weight_outlier_records.jsonl \
  --run-summary data/raw/weight_outlier_run.json \
  --device cuda:0 --resume

/workspace/LTX/.venv/bin/python scripts/analyze_and_visualize.py \
  --config config/experiment.json \
  --weight-jsonl data/raw/weight_outlier_records.jsonl \
  --processed-dir data/processed \
  --figures-dir figures \
  --tables-dir tables \
  --latex-macros report/generated_metrics.tex

/workspace/LTX/.venv/bin/python scripts/refine_report_figures.py
/workspace/LTX/.venv/bin/python scripts/int8_control_analysis.py
bash report/build.sh
```

The weight script refuses to overwrite an existing JSONL unless `--resume` is
passed. It validates the 576-module manifest and cross-checks production error
against the independent prior audit.

## Provenance

| Artifact | SHA256 |
|---|---|
| Catnip checkpoint | `d09adb8c85c1ae9681958e4c45b4f6bdcfc3e596d3782ab2f76bd9cd9824734c` |
| Week2 576-layer manifest | `c085f53dbdac584a6f53b000ba5efb59892d512dcd9b42a4a8f8f53eb87acdf9` |
| Raw 576-layer JSONL | `9346a7013b56ba49724e1b7372756057ccdee4ff8f8ae7f225903a2be5a1add5` |
| Analysis summary | `aeaf9414a7411158b42e57bce013ec2200c948684f4c6546f9bcc3e3e272d5cb` |
| Final report PDF | `9231ad0b43a76836caef9cf3a176a33190468b0f50de2e7a521710812451d000` |

The analysis creates files only under
`/workspace/catnip-fp8-outlier-statistics`; it does not modify the week2
baseline or model checkpoint.