docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such
docs/CLAUDE.md Phase 2, 2026-10-14. All moves by git mv; every archived file carries a header saying what it is, why, and where to look instead. - docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL design, kernel args, hosted acceptance test, dictionary, primitives, ontology, L8 table -- previously spread over docs/, docs/lithosananke/ and docs/03-architecture/. - docs/working/archive/historical/: finished work (session plan, test-gap audit, birthing plan, fix write-ups, the January architecture draft). - docs/working/archive/superseded/: the Hermes-VM Tripod docs and July Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working doc already flagged superseded or obsolete. - docs/working/archive/dead/: the hal_* target contract (never adopted), L4Re, metrics-and-knobs. - Papers and proposals into docs/working/papers/. - References rewritten across the repo (not logs/, not docs/patent/); CLAUDE.md's documentation section rewritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
1a4b163861
commit
7aed588f78
@@ -1,155 +0,0 @@
|
||||
<!-- Moved from docs/01-getting-started/quick-start/factorial-doe.md to docs/working/architecture/getting-started/quick-start/factorial-doe.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Describes the retired per-loop `ENABLE_LOOP_1..6`
|
||||
> compile-time toggle architecture and hardcoded local paths; the physics adaptation is now
|
||||
> driven by the L8 Jacquard runtime mode selector. Kept for historical record.
|
||||
|
||||
# Quick Start: Complete 2^6 Factorial DoE
|
||||
|
||||
## TL;DR
|
||||
|
||||
Run a **complete, exhaustive 2^6 = 64 configuration experiment** in one go, collecting all data for later analysis.
|
||||
|
||||
## Three Command Options
|
||||
|
||||
### Option 1: Quick Validation (30 min)
|
||||
Test the script and infrastructure:
|
||||
```bash
|
||||
./scripts/run_factorial_doe.sh --runs-per-config 1 QUICK_TEST
|
||||
```
|
||||
- 64 builds × 1 run = 64 total runs
|
||||
- Fast feedback on whether setup works
|
||||
- Output: `/home/rajames/CLionProjects/StarForth-DoE/experiments/QUICK_TEST/`
|
||||
|
||||
### Option 2: Standard Full DoE (2-4 hours)
|
||||
Comprehensive factorial collection:
|
||||
```bash
|
||||
./scripts/run_factorial_doe.sh --runs-per-config 30 2025_11_19_FULL_FACTORIAL
|
||||
```
|
||||
- 64 builds × 30 runs = 1,920 total runs
|
||||
- Good statistical power for main effects
|
||||
- Standard production-grade experiment
|
||||
- Output: `/home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FULL_FACTORIAL/`
|
||||
|
||||
### Option 3: High-Precision Run (6-12 hours)
|
||||
Maximum data for deep analysis:
|
||||
```bash
|
||||
./scripts/run_factorial_doe.sh --runs-per-config 100 HIGH_PRECISION_FACTORIAL
|
||||
```
|
||||
- 64 builds × 100 runs = 6,400 total runs
|
||||
- Best for detecting subtle interactions
|
||||
- Run overnight for best results
|
||||
- Output: `/home/rajames/CLionProjects/StarForth-DoE/experiments/HIGH_PRECISION_FACTORIAL/`
|
||||
|
||||
## What Gets Generated
|
||||
|
||||
```
|
||||
/home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FULL_FACTORIAL/
|
||||
├── experiment_results.csv ← All 1,920 rows of measurements
|
||||
├── experiment_summary.txt ← Timing and metadata
|
||||
├── configuration_manifest.txt ← All 64 configs listed
|
||||
├── test_matrix.txt ← Randomized execution order
|
||||
└── run_logs/
|
||||
├── 0_0_0_0_0_0_run_1.log
|
||||
├── 0_0_0_0_0_0_run_2.log
|
||||
├── ...
|
||||
└── 1_1_1_1_1_1_run_30.log
|
||||
```
|
||||
|
||||
## What's Being Tested
|
||||
|
||||
6 **independent binary feedback loops**:
|
||||
|
||||
| Loop | Toggle | What It Does |
|
||||
|------|--------|---|
|
||||
| 1 | `ENABLE_LOOP_1_HEAT_TRACKING` | Count execution frequency |
|
||||
| 2 | `ENABLE_LOOP_2_ROLLING_WINDOW` | Capture execution history |
|
||||
| 3 | `ENABLE_LOOP_3_LINEAR_DECAY` | Age words over time |
|
||||
| 4 | `ENABLE_LOOP_4_PIPELINING_METRICS` | Track word transitions |
|
||||
| 5 | `ENABLE_LOOP_5_WINDOW_INFERENCE` | Infer window width |
|
||||
| 6 | `ENABLE_LOOP_6_DECAY_INFERENCE` | Infer decay slope |
|
||||
|
||||
**All 2^6 = 64 combinations** tested:
|
||||
- `0_0_0_0_0_0` = Baseline (all OFF)
|
||||
- `1_0_0_0_0_0` = Only heat tracking
|
||||
- `0_1_0_0_0_0` = Only rolling window
|
||||
- ...
|
||||
- `1_1_1_1_1_1` = All loops ON (current optimal)
|
||||
|
||||
## During Execution
|
||||
|
||||
You'll see progress like:
|
||||
```
|
||||
═══════════════════════════════════════════════════════════
|
||||
STARFORTH COMPLETE 2^6 FACTORIAL DoE
|
||||
═══════════════════════════════════════════════════════════
|
||||
→ Factors: 6 feedback loops (LOOP_1 through LOOP_6)
|
||||
→ Configurations: 2^6 = 64
|
||||
→ Runs per config: 30
|
||||
→ TOTAL RUNS: 1,920
|
||||
→ Output: /home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FULL_FACTORIAL
|
||||
|
||||
>>> Generating randomized test matrix...
|
||||
✓ Test matrix generated
|
||||
|
||||
→ Run 1/1920 - config 0_1_0_1_1_0 #14...
|
||||
✓ Run 1/1920 completed (3s)
|
||||
→ Run 2/1920 - config 1_1_1_0_0_1 #2...
|
||||
✓ Run 2/1920 completed (2s)
|
||||
...
|
||||
```
|
||||
|
||||
The script:
|
||||
1. **Builds** each of 64 configurations (rebuilds when config changes)
|
||||
2. **Runs** tests in randomized order (no systematic bias)
|
||||
3. **Collects** metrics to CSV
|
||||
4. **Outputs** progress every run
|
||||
|
||||
## After Completion
|
||||
|
||||
Move to analysis repo to understand results:
|
||||
```bash
|
||||
cd /home/rajames/CLionProjects/StarForth-DoE-Analysis
|
||||
python3 analyze_factorial.py \
|
||||
data/2025_11_19_FULL_FACTORIAL/experiment_results.csv
|
||||
```
|
||||
|
||||
Expected analysis outputs:
|
||||
- **Main effects:** Which individual loops help most?
|
||||
- **Interactions:** Do loops work better/worse together?
|
||||
- **Optimal subset:** Best combination of loops?
|
||||
- **Trade-offs:** Performance vs complexity?
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
✅ **Rebuild every pass** - ensures clean, isolated testing
|
||||
✅ **Randomized execution** - eliminates temporal/thermal bias
|
||||
✅ **Complete factorial** - captures all interactions
|
||||
✅ **One-and-done** - collect all data, analyze later
|
||||
|
||||
## Estimated Time
|
||||
|
||||
| Runs/Config | Total | Time | When |
|
||||
|---|---|---|---|
|
||||
| 1 | 64 | 30-45 min | Quick test |
|
||||
| 30 | 1,920 | 2-4 hours | Standard |
|
||||
| 100 | 6,400 | 6-12 hours | Overnight |
|
||||
|
||||
Times depend on CPU, disk speed, and test harness overhead.
|
||||
|
||||
## Example Command
|
||||
|
||||
**Run it now:**
|
||||
```bash
|
||||
cd /home/rajames/CLionProjects/StarForth
|
||||
./scripts/run_factorial_doe.sh 2025_11_19_FULL_FACTORIAL
|
||||
```
|
||||
|
||||
**Monitor progress:**
|
||||
```bash
|
||||
tail -f /home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FULL_FACTORIAL/experiment_summary.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Ready?** Run the command above and let the experiment collect comprehensive data for downstream analysis.
|
||||
Reference in New Issue
Block a user