================================================================================
     STARFORTH PHYSICS ENGINE COMPREHENSIVE VALIDATION EXPERIMENT
                          QUICK REFERENCE CARD
================================================================================

QUICK START (3 STEPS - 10 SECONDS TO START)
─────────────────────────────────────────────────────────────────────────────

  1. Navigate to repo:
     cd /home/rajames/CLionProjects/StarForth

  2. Run experiment (2-3 hours):
     ./scripts/run_comprehensive_physics_experiment.sh ./physics_results

  3. Analyze results (30 seconds):
     python3 scripts/analyze_physics_experiment.py ./physics_results/experiment_results.csv --output ./physics_results/report.md

  4. View report:
     cat ./physics_results/report.md

================================================================================
EXPERIMENT OVERVIEW
─────────────────────────────────────────────────────────────────────────────

  Total Runs:     90 (30 per configuration)
  Configurations: 3
    - A (Baseline):      ENABLE_HOTWORDS_CACHE=0  ENABLE_PIPELINING=0
    - B (Cache):         ENABLE_HOTWORDS_CACHE=1  ENABLE_PIPELINING=0
    - C (Full):          ENABLE_HOTWORDS_CACHE=1  ENABLE_PIPELINING=1

  Workload:       100,000 dictionary lookups per run
  Build Profile:  fastest
  Duration:       ~2-3 hours
  Output:         CSV with all metrics

================================================================================
MONITORING PROGRESS (while running in another terminal)
─────────────────────────────────────────────────────────────────────────────

  # Watch CSV grow in real-time
  watch -n 5 'wc -l physics_results/experiment_results.csv'

  # Check completed runs per config
  for c in A_BASELINE B_CACHE C_FULL; do
    echo "$c: $(ls physics_results/run_logs/${c}*.log 2>/dev/null | wc -l) runs"
  done

  # View latest run logs
  ls -lhrt physics_results/run_logs | tail -10

================================================================================
FILE LOCATIONS
─────────────────────────────────────────────────────────────────────────────

  Documentation:
    - docs/COMPREHENSIVE_PHYSICS_ENGINE_VALIDATION_PROTOCOL.md
    - docs/PHYSICS_EXPERIMENT_EXECUTION_GUIDE.md
    - PHYSICS_EXPERIMENT_README.md (overview)
    - EXPERIMENT_QUICK_REFERENCE.txt (this file)

  Scripts:
    - scripts/run_comprehensive_physics_experiment.sh (main orchestrator)
    - scripts/extract_benchmark_metrics.py (metric parser)
    - scripts/analyze_physics_experiment.py (statistical analysis)

  Output Files (created during execution):
    - experiment_results.csv (90 data rows + 1 header)
    - run_logs/ (90 individual run logs)
    - experiment_summary.txt (execution summary)
    - analysis_report.md (generated by analysis script)

================================================================================
SUCCESS CRITERIA
─────────────────────────────────────────────────────────────────────────────

  Configuration A (Baseline):
    ✓ All 30 runs complete without error
    ✓ 100,000 lookups per run
    ✓ Metrics in CSV
    ✓ Mean latency with 95% CI

  Configuration B (Cache):
    ✓ Cache hit rate > 20%
    ✓ Speedup > 1.1× vs Baseline
    ✓ 95% CI excludes 1.0 (significant)
    ✓ CV < 10% (reproducible)

  Configuration C (Full):
    ✓ Prediction accuracy > 60%
    ✓ Speedup > Configuration B
    ✓ Pattern diversity saturation > 90%
    ✓ Window final size < initial size

================================================================================
TROUBLESHOOTING QUICK REFERENCE
─────────────────────────────────────────────────────────────────────────────

  Build fails?
    → Run manually: make clean && make fastest
    → Check compiler: gcc --version

  Commands not found?
    → Verify implementation: grep -r "BENCH-DICT-LOOKUP" src/
    → Rebuild: make clean && make fastest

  CSV parsing fails?
    → Check output: cat run_logs/A_BASELINE_run_1.log
    → Update regex in extract_benchmark_metrics.py

  Out of space?
    → Clean builds: make clean && rm -rf build/
    → Remove old results: rm -rf physics_results_old/

  Need more detailed help?
    → See: docs/PHYSICS_EXPERIMENT_EXECUTION_GUIDE.md

================================================================================
CUSTOMIZATION OPTIONS
─────────────────────────────────────────────────────────────────────────────

  Fewer runs for testing:
    Edit script, change: RUNS_PER_CONFIG=5  (instead of 30)

  Adjust benchmark iterations:
    Edit script, change: BENCH_ITERATIONS=10000  (instead of 100000)

  Different build profile:
    Edit script, change: BUILD_PROFILE="fast"  (instead of "fastest")

  Tune physics knobs:
    Add to make: ADAPTIVE_SHRINK_RATE=50 ADAPTIVE_MIN_WINDOW_SIZE=128

================================================================================
EXPECTED OUTPUT EXAMPLE
─────────────────────────────────────────────────────────────────────────────

  When experiment runs:
    ════════════════════════════════════════════════════════════
       ⚡ Building the Fastest Forth in the West! ⚡
    ════════════════════════════════════════════════════════════

    >>> Building Configuration: A_BASELINE
    ✓ Build completed for A_BASELINE

    >>> Run 1/30 for A_BASELINE...
    ✓ Run 1 completed (2.3s)
    ...
    ✓ All 90 experiments completed successfully!
    ✓ Results saved to: ./physics_results/experiment_results.csv
    ✓ Total runtime: 145 minutes

  When analysis completes:
    ✓ Report written to: ./physics_results/analysis_report.md

================================================================================
ANALYSIS REPORT STRUCTURE
─────────────────────────────────────────────────────────────────────────────

  The generated analysis_report.md contains:

    1. Executive Summary
    2. Per-Configuration Statistics (mean, median, stddev, CI)
    3. Comparative Analysis (speedup factors with credible intervals)
    4. Success Criteria Validation (checklist)
    5. Hypothesis Testing (null hypothesis rejection decision)
    6. Methodology Notes
    7. Conclusion

  Key Tables:
    - Runtime statistics for each configuration
    - Speedup comparison B vs A, C vs B, C vs A
    - Effect sizes and reproducibility metrics
    - Credible intervals and significance testing

================================================================================
PERFORMANCE TIPS
─────────────────────────────────────────────────────────────────────────────

  To optimize experiment runtime:

    1. Disable background services:
       systemctl stop docker          # If applicable
       sudo killall updatedb          # Stop file indexing

    2. Use fastest build (default in script)

    3. Set CPU governor to performance (if supported):
       echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

    4. Run in dedicated terminal window
       Avoid other I/O during experiment

    5. Minimize system load
       Close unnecessary applications

================================================================================
PUBLICATION CHECKLIST
─────────────────────────────────────────────────────────────────────────────

  When publishing results:

    ✓ Report all three statistics (mean, 95% CI, n=30)
    ✓ Include experiment_results.csv in supplementary materials
    ✓ Include per-run logs for reproducibility
    ✓ Reference or include the protocol document
    ✓ List hardware details (CPU, RAM, OS)
    ✓ Note any special conditions during execution
    ✓ Make code available (StarForth is open source)
    ✓ Discuss limitations (deterministic workload, single system, etc.)

================================================================================
DOCUMENT CROSS-REFERENCES
─────────────────────────────────────────────────────────────────────────────

  For complete information, see:

    PROTOCOL (Formal specification):
      → docs/COMPREHENSIVE_PHYSICS_ENGINE_VALIDATION_PROTOCOL.md

    EXECUTION GUIDE (Step-by-step walkthrough):
      → docs/PHYSICS_EXPERIMENT_EXECUTION_GUIDE.md

    OVERVIEW (Architecture and design):
      → PHYSICS_EXPERIMENT_README.md

    QUICK REFERENCE (This file):
      → EXPERIMENT_QUICK_REFERENCE.txt

    IMPLEMENTATION (Actual physics code):
      → include/physics_hotwords_cache.h
      → include/physics_pipelining_metrics.h
      → include/rolling_window_of_truth.h
      → include/rolling_window_knobs.h

================================================================================
READY TO EXECUTE
─────────────────────────────────────────────────────────────────────────────

  ✓ All scripts created and tested
  ✓ Scripts are executable with proper permissions
  ✓ Build system verified (all 731 tests passing)
  ✓ Documentation complete and comprehensive
  ✓ CSV schema defined and ready
  ✓ Analysis framework working

  To start: ./scripts/run_comprehensive_physics_experiment.sh ./physics_results

================================================================================
                         November 6, 2025
================================================================================
