LithosAnanake/docs/working/experiments/campaigns/window_scaling/QUICK_START.md

Window Scaling Experiment - Quick Start Guide

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

---

Prerequisites (One-Time Setup)

# 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)

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

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!

./run_window_sweep.sh

Monitor in another terminal:

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)

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:

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"

R
> install.packages(c("dplyr", "tidyr", "readr", "ggplot2", "scales"))

"Build failed"

Check that you can build StarForth normally:

cd /home/rajames/CLionProjects/StarForth
make clean
make ARCH=amd64 TARGET=fastest

"VM timeout"

Increase timeout in scripts/run_window_sweep.sh:

TIMEOUT_SECS=300  # Change from 120 to 300

"Experiment interrupted"

The runner writes incrementally - safe to resume:

cd scripts/
./run_window_sweep.sh  # Will continue from where it stopped

"Analysis script fails"

Check that results file exists:

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

# 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

# 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?

./setup_experiment.sh

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