# Reproduction

This repository supports four practical reproduction levels. Start with Level 1 unless you already have local source data, clip-bank videos, prediction MP4s, and model checkpoints.

## Level 1: Paper Artifact Regeneration

Goal: regenerate lightweight tables and plots from included small CSV/JSON artifacts.

Prerequisites:

- CPU Python environment
- NumPy
- matplotlib

Command:

```bash
python scripts/make_release_artifacts.py \
  --artifacts-dir artifacts \
  --out-dir outputs/release_level1
```

Expected outputs:

```text
outputs/release_level1/performance_tradeoff.png
outputs/release_level1/temporal_mad_n30.png
outputs/release_level1/expanded_quality_table.tex
outputs/release_level1/paired_comparison_table.tex
```

No GPU, model weights, source data, clip-bank MP4s, or prediction MP4s are needed.

## Level 2: Metric / Baseline Recalculation

Goal: recompute MAD, SSIM, Persistence, and History Farneback metrics from local videos.

Prerequisites:

- local clip-bank MP4s
- local model prediction MP4s and result JSONs, if recomputing model metrics
- CPU metric/baseline environment

Example for the N=30 validation:

```bash
python scripts/compute_extended_metrics.py \
  --results-root results/vtc_n30_ltx2b \
  --clip-manifest manifests/clips/vtc_n30/clip_manifest.csv \
  --out-dir outputs/tables/vtc_n30_ltx2b
```

For baselines only:

```bash
python scripts/compute_extended_metrics.py \
  --baselines-only \
  --clip-manifest manifests/clips/vtc_n30/clip_manifest.csv \
  --out-dir outputs/tables/vtc_n30_ltx2b_baselines
```

Prediction MP4s, clip-bank MP4s, and full result trees are not included in this repository.

## Level 3: Model Inference

Goal: rerun model inference with external checkpoints and GPU setup.

Prerequisites:

- generated clip bank from Level 4
- external model checkpoints and dependencies
- GPU environment

### Original N=5 Benchmark

Build matrix files from source matrices if needed:

```bash
python -m src.cli.main build-matrix \
  --config manifests/matrices/ltx_matrix.yaml \
  --clip-manifest manifests/clips/clip_manifest.csv \
  --manifests-root manifests/generated

python -m src.cli.main build-matrix \
  --config manifests/matrices/ltx_13b_matrix.yaml \
  --clip-manifest manifests/clips/clip_manifest.csv \
  --manifests-root manifests/generated

python -m src.cli.main build-matrix \
  --config manifests/matrices/svd_matrix.yaml \
  --clip-manifest manifests/clips/clip_manifest.csv \
  --manifests-root manifests/generated

python -m src.cli.main build-matrix \
  --config manifests/matrices/wan_matrix.yaml \
  --clip-manifest manifests/clips/clip_manifest.csv \
  --manifests-root manifests/generated
```

Run sweeps:

```bash
python -m src.cli.main sweep --config manifests/generated/experiment_matrix_ltx.yaml
python -m src.cli.main sweep --config manifests/generated/experiment_matrix_ltx_13b.yaml
python -m src.cli.main sweep --config manifests/generated/experiment_matrix_svd.yaml
python -m src.cli.main sweep --config manifests/generated/experiment_matrix_wan.yaml
```

### Expanded N=30 LTX-2B Run

Build the N=30 LTX-2B matrix if needed:

```bash
python -m src.cli.main build-matrix \
  --config manifests/matrices/vtc_n30_512_ltx2b.yaml \
  --clip-manifest manifests/clips/vtc_n30/clip_manifest.csv \
  --manifests-root manifests/generated/vtc_n30
```

Run the N=30 LTX-2B sweep:

```bash
python -m src.cli.main sweep \
  --config manifests/generated/vtc_n30/experiment_matrix_vtc_n30_512_ltx2b.yaml
```

These commands require external source data, model checkpoints, model-specific dependencies, and GPU resources.

## Level 4: Rebuild Source Clip Bank

Goal: generate `conditioning.mp4` and `ground_truth.mp4` clip-bank videos from external CARLA/MILE/Roach source frames.

Set the external data root:

```bash
export GENPD_DATA_ROOT=/path/to/carla_mile_roach_frames
```

Original N=5 clip bank:

```bash
python -m src.cli.main build-clip-bank \
  --config manifests/clips/clip_sources.yaml \
  --clip-bank-root clip_bank \
  --manifests-root manifests/clips
```

Expanded N=30 clip bank:

```bash
python -m src.cli.main build-clip-bank \
  --config manifests/clips/clip_sources_vtc_n30.yaml \
  --clip-bank-root clip_bank/vtc_n30 \
  --manifests-root manifests/clips/vtc_n30
```

The source images must be obtained separately. Generated clip banks are local artifacts and are gitignored.

## Validation

Run CPU tests:

```bash
PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -v
```

Expected manifest and matrix counts are tested:

- original N=5 clip manifest: 10 rows
- expanded N=30 clip manifest: 30 rows
- LTX matrix: 10 experiments
- LTX-13B matrix: 10 experiments
- SVD matrix: 10 experiments
- Wan matrix: 20 experiments
- N=30 LTX-2B matrix: 30 experiments

Run the Level-1 artifact sanity check:

```bash
python scripts/make_release_artifacts.py \
  --artifacts-dir artifacts \
  --out-dir outputs/release_level1
```