<!-- Moved from experiments/window_scaling/QUICK_START.md to docs/working/experiments/campaigns/window_scaling/QUICK_START.md on 2026-06-16 (docs reorg Phase 2) -->
# Window Scaling Experiment - Quick Start Guide

**Purpose**: Validate the James Law of Computational Dynamics: `Λ = W / (DoF + 1)`

---

## Prerequisites (One-Time Setup)

```bash
# Install R packages
R
> install.packages(c("dplyr", "tidyr", "readr", "ggplot2", "scales"))
> install.packages(c("viridis", "patchwork"))  # Optional but recommended
> q()
```

---

## Four-Step Workflow (RECOMMENDED: Pre-Build Approach)

### Step 1: Setup & Validation (~5 minutes)

```bash
cd /home/rajames/CLionProjects/StarForth/experiments/window_scaling_james_law_run_one_invalid.
./setup_experiment.sh
```

**What it does**:
- ✓ Checks R, make, gcc are installed
- ✓ Checks R packages
- ✓ Generates shuffled run matrix (2,880 rows)
- ✓ Performs test build
- ✓ Runs test VM execution
- ✓ Estimates experiment duration

**Expected output**: "Setup Complete - Ready to Run Experiment"

---

### Step 2: Pre-Build All Configurations (~1.5 hours)

⚠️ **NEW STEP**: Build all 96 unique configs ONCE, then reuse them

```bash
cd scripts/
./prebuild_all_configs.sh
```

**What it does**:
- Builds all 96 unique (DoF, Window) configurations
- Stores in `experiments/bin/` (safe from `make clean`)
- One-time cost: ~1.5 hours
- Binaries can be reused for multiple experiment runs

**Expected output**:
```
[96/96] Building: DoF=7 W=65536
  ✓ Built: experiments/bin/dof7_w65536/starforth

✓ All 96 configurations built successfully!
Binaries stored in: experiments/bin/
```

---

### Step 3: Execute Experiment (~4-5 hours)

⚠️ **MUCH FASTER**: No rebuilds, just pure execution!

```bash
./run_window_sweep.sh
```

**Monitor in another terminal**:
```bash
tail -f ../results_run_01_2025_12_08/raw/experiment.log
```

**What it does**:
- Uses pre-built binaries from `experiments/bin/`
- Executes 2,880 runs (NO rebuilds!)
- Outputs to: `results/raw/window_sweep_results.csv`

**Progress format**:
```
[123/2880] DoF=5 W=8192 Rep=12 | 0110000 | ETA: 3h20m (8.5 runs/min)
  → Running: experiments/bin/dof5_w8192/starforth
  ✓ Success
```

**Time savings**: ~3-5 hours faster than rebuild approach!

---

### Step 4: Analyze Results (~5 minutes)

```bash
cd scripts/
./analyze_results.R
```

**What it does**:
- Computes `K = Λ × (DoF + 1) / W` for all runs
- Tests if `K ≈ 1.0` (James Law validation)
- Identifies critical window threshold
- Generates 5 publication-quality plots

**Output files**:
```
results/processed/
├── james_law_validation.csv       # K statistics by condition
├── window_sweep_processed.csv     # Full dataset with metrics
├── summary_statistics.rds         # R data object
├── K_distribution_by_condition.png
├── K_vs_window_size.png
├── stability_heatmap.png
├── K_deviation_heatmap.png
└── performance_vs_window.png
```

**Key output**:
```
==================================================
JAMES LAW VALIDATION: OVERALL
==================================================

K Statistic Across All Runs:
  Mean(K):        1.0023
  Std(K):         0.0451
  CV(K):          4.50%
  Mean |K-1.0|:   0.0156
  Max |K-1.0|:    0.0823

James Law Validation Criteria:
  [✓] Mean(K) ∈ [0.95, 1.05]:  1.0023
  [✓] Std(K) < 0.1:            0.0451
  [✓] Max|K-1.0| < 0.1:        0.0823

🎉 JAMES LAW VALIDATED: K ≈ 1.0 across all conditions
```

---

## Alternative: Rebuild-Per-Run Approach (For Doubters)

If you prefer the simpler (but slower) approach:

```bash
cd scripts/
./run_window_sweep.sh  # ~8-10 hours (rebuilds as needed)
```

This rebuilds the VM whenever the configuration changes. Good for:
- Verifying pre-build approach
- Systems where disk space is limited
- Debugging build issues

**Not recommended** for normal use - pre-build is 3-5 hours faster!

---

## File Locations

### Input
- **Run matrix**: `run_matrix_shuffled.csv` (generated by setup)
- **Pre-built binaries**: `../../bin/dof{X}_w{Y}/starforth` (96 configs)
- **Workload**: `../../conf/init-l8-omni.4th`

### Output
- **Raw data**: `results/raw/window_sweep_results.csv` (68 columns × 2,880 rows)
- **Log file**: `results/raw/experiment.log`
- **Processed data**: `results/processed/*.csv`
- **Visualizations**: `results/processed/*.png`

---

## Troubleshooting

### "R packages not found"
```bash
R
> install.packages(c("dplyr", "tidyr", "readr", "ggplot2", "scales"))
```

### "Build failed"
Check that you can build StarForth normally:
```bash
cd /home/rajames/CLionProjects/StarForth
make clean
make ARCH=amd64 TARGET=fastest
```

### "VM timeout"
Increase timeout in `scripts/run_window_sweep.sh`:
```bash
TIMEOUT_SECS=300  # Change from 120 to 300
```

### "Experiment interrupted"
The runner writes incrementally - safe to resume:
```bash
cd scripts/
./run_window_sweep.sh  # Will continue from where it stopped
```

### "Analysis script fails"
Check that results file exists:
```bash
ls -lh ../results_run_01_2025_12_08/raw/window_sweep_results.csv
```

---

## Expected Results

### If James Law Holds
- **Mean(K) ≈ 1.0** across all conditions
- **Std(K) < 0.1** (tight distribution)
- K consistent across DoF and window sizes
- **Conclusion**: Universal scaling law validated ✅

### If Critical Threshold Found
- K ≈ 1.0 for W < W_critical
- K deviates for W ≥ W_critical
- System collapses (high CV, poor performance)
- **Conclusion**: Phase transition discovered ✅

### Either Way
You've conducted a rigorous scientific experiment testing a fundamental hypothesis about computational dynamics.

---

## Timeline

| Phase | Duration | Deliverable |
|-------|----------|-------------|
| Setup | 5 min | Environment validated, matrix generated |
| Execute | 24-48 hrs | 2,880 runs complete |
| Analyze | 5 min | Plots + statistics |
| **TOTAL** | ~2 days | James Law proven or disproven |

---

## What to Do with Results

### If Validated ✅
1. Add to patent as Claim 25
2. Write arXiv preprint
3. Submit to Physical Review E
4. Prepare DARPA Phase I white paper

### If Not Validated ⚠️
1. Examine K vs DoF relationship (logarithmic? power-law?)
2. Identify W_critical boundary
3. Characterize phase transition
4. Still publishable (negative results are valid science)

---

## Command Summary

### Recommended: Pre-Build Approach
```bash
# One-time setup
./setup_experiment.sh

# Pre-build all configs (1.5 hours, one-time)
cd scripts/
./prebuild_all_configs.sh

# Run experiment (4-5 hours, no rebuilds!)
./run_window_sweep.sh

# Monitor progress
tail -f ../results_run_01_2025_12_08/raw/experiment.log

# Analyze results_run_01_2025_12_08
./analyze_results.R

# View plots
cd ../results_run_01_2025_12_08/processed/
open *.png  # macOS
xdg-open *.png  # Linux
```

### Alternative: Rebuild Approach
```bash
# One-time setup
./setup_experiment.sh

# Run experiment (8-10 hours, rebuilds included)
cd scripts/
./run_window_sweep.sh

# ... rest same as above
```

---

## Support

Questions? Check:
1. `README.md` - Full documentation
2. `IMPLEMENTATION_SUMMARY.md` - Technical details
3. `results/raw/experiment.log` - Runtime debugging

---

**Ready?**

```bash
./setup_experiment.sh
```

**Let's prove (or disprove) a fundamental law of computation.**