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,4 +1,4 @@
|
||||
<!-- Moved from docs/03-architecture/README.md to docs/working/architecture/03-architecture/README.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
<!-- Moved from docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md to docs/working/architecture/03-architecture/README.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
# Architecture
|
||||
|
||||
This directory contains system architecture documentation for StarForth's core subsystems and the path to StarKernel and StarshipOS.
|
||||
|
||||
@@ -1,275 +0,0 @@
|
||||
<!-- Moved from docs/03-architecture/adaptive-systems/loop-5-sketch.md to docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `window-inference-redesign.md`
|
||||
> (Levene's-test window inference — the shipped Loop #5 mechanism). This undated sketch ended
|
||||
> in an open question and was never approved as designed. Kept for historical record.
|
||||
|
||||
# Loop #5: Context-Aware Window Tuning - Design Sketch
|
||||
|
||||
## The Challenge
|
||||
|
||||
**Current state:** Window size shrinks based on pattern diversity, but we don't know if shrinking improves or hurts **pipelining prediction accuracy**.
|
||||
|
||||
**Goal:** Use actual prefetch hit rate to guide window size tuning via binary chop search.
|
||||
|
||||
---
|
||||
|
||||
## What Loop #5 Should Do
|
||||
|
||||
### High-Level Flow
|
||||
|
||||
1. **Measure**: Track global pipelining metrics across ALL words
|
||||
- Total speculative prefetch attempts
|
||||
- Successful prefetch hits
|
||||
- Current accuracy = hits / attempts
|
||||
|
||||
2. **Trigger**: Periodically (e.g., every 1000 executions when warm)
|
||||
- Calculate prediction accuracy at current effective_window_size
|
||||
- Call binary chop to suggest next size to try
|
||||
|
||||
3. **Adapt**: Shrink or grow effective_window_size based on accuracy trend
|
||||
- If smaller window → better accuracy: keep shrinking
|
||||
- If smaller window → worse accuracy: grow back up
|
||||
- Converge to sweet spot
|
||||
|
||||
4. **Measure**: Record the accuracy at each window size tried
|
||||
- Build history of (window_size → accuracy) pairs
|
||||
- Use this history to accelerate convergence
|
||||
|
||||
---
|
||||
|
||||
## Architecture Needed
|
||||
|
||||
### 1. VM-Level Metrics (New)
|
||||
|
||||
**File:** `include/vm.h` (add to VM struct)
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
uint64_t prefetch_attempts; /* Total speculative prefetch calls */
|
||||
uint64_t prefetch_hits; /* Successful hits (word was looked up next) */
|
||||
uint64_t window_tuning_checks; /* How many times we've checked window size */
|
||||
uint32_t last_checked_window_size;
|
||||
double last_checked_accuracy;
|
||||
uint32_t suggested_next_size; /* What binary chop recommends trying */
|
||||
} PipelineGlobalMetrics;
|
||||
```
|
||||
|
||||
**Add to VM struct:**
|
||||
```c
|
||||
struct VM {
|
||||
// ... existing fields ...
|
||||
PipelineGlobalMetrics pipeline_metrics; /* NEW: aggregated metrics */
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Update Prefetch Feedback (in vm.c)
|
||||
|
||||
**When speculative prefetch succeeds:**
|
||||
```c
|
||||
// In execute_colon_word(), after promotion:
|
||||
if (spec_entry && vm->hotwords_cache && ENABLE_HOTWORDS_CACHE)
|
||||
{
|
||||
spec_entry->execution_heat = HOTWORDS_EXECUTION_HEAT_THRESHOLD + 1;
|
||||
hotwords_cache_promote(vm->hotwords_cache, spec_entry);
|
||||
|
||||
// NEW: Record the prefetch attempt globally
|
||||
vm->pipeline_metrics.prefetch_attempts++;
|
||||
prev_word->transition_metrics->prefetch_attempts++; // Per-word too
|
||||
}
|
||||
```
|
||||
|
||||
**When word is actually looked up (check if it was speculated):**
|
||||
```c
|
||||
// In vm_interpret_word(), during dictionary lookup:
|
||||
if (entry && ENABLE_PIPELINING && vm->hotwords_cache)
|
||||
{
|
||||
// NEW: Check if this word was in speculated cache (dirty bit or timestamp)
|
||||
if (word_was_speculatively_promoted_recently(entry))
|
||||
{
|
||||
vm->pipeline_metrics.prefetch_hits++; // Global metric
|
||||
// per_word_metrics->prefetch_hits++; // Already done in prefetch logic
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Window Tuning Decision Loop
|
||||
|
||||
**New function:** `physics_pipelining_metrics.c`
|
||||
|
||||
```c
|
||||
/**
|
||||
* Suggest window size via binary chop based on prefetch accuracy trend.
|
||||
* Called periodically (every 1000 executions when pipelining is enabled).
|
||||
*/
|
||||
uint32_t loop_5_binary_chop_suggest_window(
|
||||
const PipelineGlobalMetrics *global,
|
||||
uint32_t current_window_size,
|
||||
uint32_t min_window,
|
||||
uint32_t max_window)
|
||||
{
|
||||
if (global->prefetch_attempts == 0)
|
||||
return current_window_size; /* Not enough data yet */
|
||||
|
||||
double current_accuracy = (double)global->prefetch_hits / (double)global->prefetch_attempts;
|
||||
|
||||
/* Binary chop: try smaller window first (aggressive shrinking)
|
||||
* If accuracy drops, back off and try larger windows */
|
||||
|
||||
if (global->window_tuning_checks == 0)
|
||||
{
|
||||
/* First check: try shrinking by 25% */
|
||||
return (current_window_size * 75) / 100;
|
||||
}
|
||||
|
||||
/* Compare current accuracy to last check */
|
||||
double accuracy_delta = current_accuracy - global->last_checked_accuracy;
|
||||
|
||||
if (accuracy_delta > 0.01) /* Improvement threshold: 1% */
|
||||
{
|
||||
/* Accuracy improved! Try shrinking more */
|
||||
uint32_t smaller = (current_window_size * 75) / 100;
|
||||
return (smaller > min_window) ? smaller : min_window;
|
||||
}
|
||||
else if (accuracy_delta < -0.01)
|
||||
{
|
||||
/* Accuracy degraded. Try growing instead */
|
||||
uint32_t larger = (current_window_size * 133) / 100; /* Grow by ~33% */
|
||||
return (larger < max_window) ? larger : max_window;
|
||||
}
|
||||
else
|
||||
{
|
||||
/* Plateau: stick with current size */
|
||||
return current_window_size;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Integration Point
|
||||
|
||||
**In rolling_window_of_truth.c: `rolling_window_check_adaptive_shrink()`**
|
||||
|
||||
```c
|
||||
void rolling_window_check_adaptive_shrink(RollingWindowOfTruth* window)
|
||||
{
|
||||
// ... existing adaptive shrinking code ...
|
||||
|
||||
/* Loop #5: Binary chop window tuning (Phase 2 IMPLEMENTATION) */
|
||||
if (ENABLE_PIPELINING && window->is_warm)
|
||||
{
|
||||
window->adaptive_check_count++;
|
||||
|
||||
/* Check every 1000 executions for tuning opportunity */
|
||||
if (window->adaptive_check_count % 1000 == 0)
|
||||
{
|
||||
PipelineGlobalMetrics *metrics = &vm->pipeline_metrics;
|
||||
|
||||
/* Calculate current accuracy */
|
||||
double current_accuracy = (metrics->prefetch_attempts > 0)
|
||||
? (double)metrics->prefetch_hits / (double)metrics->prefetch_attempts
|
||||
: 0.0;
|
||||
|
||||
/* Ask binary chop for next window size to try */
|
||||
uint32_t suggested_size = loop_5_binary_chop_suggest_window(
|
||||
metrics,
|
||||
window->effective_window_size,
|
||||
ADAPTIVE_MIN_WINDOW_SIZE,
|
||||
ROLLING_WINDOW_SIZE
|
||||
);
|
||||
|
||||
/* Apply if different */
|
||||
if (suggested_size != window->effective_window_size)
|
||||
{
|
||||
log_message(LOG_INFO,
|
||||
"Loop #5: Binary chop tuning: %u → %u (accuracy %.2f%%, %lu/%lu hits)",
|
||||
window->effective_window_size,
|
||||
suggested_size,
|
||||
current_accuracy * 100.0,
|
||||
metrics->prefetch_hits,
|
||||
metrics->prefetch_attempts);
|
||||
|
||||
window->effective_window_size = suggested_size;
|
||||
}
|
||||
|
||||
/* Record this check for next iteration */
|
||||
metrics->last_checked_window_size = window->effective_window_size;
|
||||
metrics->last_checked_accuracy = current_accuracy;
|
||||
metrics->window_tuning_checks++;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
### A. Accuracy Measurement
|
||||
- **Count**: Successful speculative promotions that were actually used
|
||||
- **Challenge**: How to know if lookup was "predicted" vs "natural"?
|
||||
- Option 1: Mark speculatively-promoted entries with a timestamp/flag
|
||||
- Option 2: Track word IDs predicted and check if they match next lookup
|
||||
- Option 3: Use per-word prefetch metrics already collected
|
||||
|
||||
### B. Tuning Frequency
|
||||
- **Every 1000 executions** (when window is warm)
|
||||
- Could be tunable: `make WINDOW_TUNING_FREQUENCY=1000`
|
||||
|
||||
### C. Search Strategy
|
||||
- **Greedy shrinking first**: Try smaller windows aggressively
|
||||
- **Backoff on degradation**: If accuracy drops, grow back up
|
||||
- **Convergence**: Stop when oscillating around sweet spot
|
||||
|
||||
### D. Knobs Needed (Makefile)
|
||||
```bash
|
||||
make ENABLE_PIPELINING=1 # Must be enabled for Loop #5
|
||||
make WINDOW_TUNING_FREQUENCY=1000 # How often to check
|
||||
make WINDOW_TUNING_ACCURACY_THRESHOLD=1 # % improvement to continue shrinking
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Approach
|
||||
|
||||
Once Loop #5 is wired, DoE would test:
|
||||
- **A_BASELINE**: No optimizations
|
||||
- **A_B_CACHE**: Cache only
|
||||
- **A_C_FULL**: Window tuning with pipelining only
|
||||
- **A_B_C_FULL**: Cache + window tuning + pipelining
|
||||
|
||||
**Metrics to collect:**
|
||||
- Final effective_window_size (what did it converge to?)
|
||||
- Final prefetch accuracy (%)
|
||||
- Throughput improvement vs baseline
|
||||
|
||||
---
|
||||
|
||||
## Risks & Unknowns
|
||||
|
||||
1. **Overhead**: Checking accuracy every 1000 executions adds latency
|
||||
2. **Noise**: If accuracy is noisy, binary chop might oscillate
|
||||
3. **Workload-dependent**: Optimal window size might vary by workload
|
||||
4. **False positives**: Speculative lookup might not correlate with prediction
|
||||
|
||||
---
|
||||
|
||||
## Sketch Summary
|
||||
|
||||
**Loop #5 would:**
|
||||
1. Track global prefetch accuracy (hits/attempts)
|
||||
2. Every 1000 executions, ask binary chop: "Is current window size optimal?"
|
||||
3. Binary chop suggests shrinking, holding, or growing based on accuracy trend
|
||||
4. Apply suggestion and record for next iteration
|
||||
5. Over time, converge to window size that maximizes prediction accuracy
|
||||
|
||||
**Code locations if implemented:**
|
||||
- VM struct: Add PipelineGlobalMetrics field
|
||||
- vm.c: Update global metrics on prefetch attempts/hits
|
||||
- physics_pipelining_metrics.c: `loop_5_binary_chop_suggest_window()`
|
||||
- rolling_window_of_truth.c: Call binary chop from adaptive shrink check
|
||||
|
||||
**Effort**: ~150 LOC across 3-4 files
|
||||
|
||||
---
|
||||
|
||||
**Question for user:** Does this architecture align with what you had in mind for Loop #5?
|
||||
@@ -1,243 +0,0 @@
|
||||
<!-- Moved from docs/03-architecture/hal/README.md to docs/working/architecture/03-architecture/hal/README.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This document family
|
||||
> describes a proposed `hal_*`-named interface and a `src/platform/<platform>/` layout that
|
||||
> was never adopted as written. The implemented kernel HAL lives in `src/starkernel/hal/`
|
||||
> with different (time-backend-style) naming. Treat all five documents here as design intent,
|
||||
> not the current API. For current architecture see `.claude/CLAUDE.md`.
|
||||
|
||||
# Hardware Abstraction Layer (HAL) Documentation
|
||||
|
||||
This directory contains comprehensive documentation for StarForth's Hardware Abstraction Layer (HAL), which enables the evolution from hosted VM to StarKernel to StarshipOS.
|
||||
|
||||
> **HISTORICAL — L4Re/Fiasco.OC**: L4Re references throughout this directory's docs describe a target that was a supported platform through mid-2026. L4Re support has since been removed as an active target — `src/platform/l4re/time.c` and related `#ifdef __l4__` code are retained for reference but no longer wired into any build.
|
||||
|
||||
---
|
||||
|
||||
## Document Organization
|
||||
|
||||
Read in this order for full understanding:
|
||||
|
||||
### 1. **[overview.md](overview.md)** - Start Here
|
||||
**What:** High-level HAL architecture, design principles, and rationale
|
||||
**Who:** Everyone (developers, architects, contributors)
|
||||
**Why read:** Understand the problem HAL solves and how it fits into StarForth → StarKernel → StarshipOS
|
||||
|
||||
**Key sections:**
|
||||
- The Problem (why HAL is necessary)
|
||||
- Architecture Overview (3-layer model)
|
||||
- Design Principles (VM purity, contract-first, testability)
|
||||
- HAL Subsystems (time, interrupts, memory, console, CPU)
|
||||
- HAL and Physics Subsystems
|
||||
- Success Criteria
|
||||
|
||||
---
|
||||
|
||||
### 2. **[interfaces.md](interfaces.md)** - The Contract
|
||||
**What:** Detailed HAL interface specifications (function signatures, semantics, guarantees)
|
||||
**Who:** VM developers, platform implementers
|
||||
**Why read:** Understand exactly what each HAL function does and requires
|
||||
|
||||
**Key sections:**
|
||||
- Time & Timers interface (`hal_time.h`)
|
||||
- Interrupts interface (`hal_interrupt.h`)
|
||||
- Memory interface (`hal_memory.h`)
|
||||
- Console interface (`hal_console.h`)
|
||||
- CPU interface (`hal_cpu.h`)
|
||||
- Panic/Error interface (`hal_panic.h`)
|
||||
- Interface safety summary (ISR-safe, thread-safe)
|
||||
|
||||
**Critical details:**
|
||||
- Function semantics (what it does, guaranteed behavior)
|
||||
- Error handling (when it can fail, how to handle)
|
||||
- Performance expectations (latency, overhead)
|
||||
- Concurrency model (thread-safe? ISR-safe?)
|
||||
|
||||
---
|
||||
|
||||
### 3. **[platform-implementations.md](platform-implementations.md)** - How to Implement
|
||||
**What:** Platform-specific implementation examples and guidance
|
||||
**Who:** Platform developers adding HAL support for new targets
|
||||
**Why read:** Learn how to implement HAL for a specific platform
|
||||
|
||||
**Key sections:**
|
||||
- Platform directory structure
|
||||
- Linux HAL implementation (reference platform)
|
||||
- Kernel HAL implementation (StarKernel)
|
||||
- Platform testing strategy
|
||||
- Common implementation pitfalls
|
||||
|
||||
**Includes complete code examples for:**
|
||||
- Linux (POSIX, hosted)
|
||||
- Kernel (freestanding, bare metal)
|
||||
|
||||
---
|
||||
|
||||
### 4. **[migration-plan.md](migration-plan.md)** - Refactoring Guide
|
||||
**What:** Step-by-step plan for refactoring existing StarForth to use HAL
|
||||
**Who:** Core developers doing the migration work
|
||||
**Why read:** Execute the HAL migration safely with zero regressions
|
||||
|
||||
**Key sections:**
|
||||
- 7-phase migration strategy
|
||||
- Incremental refactoring approach
|
||||
- Test validation after each phase
|
||||
- Rollback strategy
|
||||
- Timeline estimates (2-4 weeks)
|
||||
|
||||
**Phases:**
|
||||
1. Define HAL interfaces (headers only)
|
||||
2. Implement HAL for Linux
|
||||
3. Migrate VM core to use HAL
|
||||
4. Migrate physics subsystems to use HAL
|
||||
5. Migrate REPL and word implementations
|
||||
6. Implement HAL for L4Re (optional validation)
|
||||
7. Validate deterministic behavior
|
||||
|
||||
---
|
||||
|
||||
### 5. **[starkernel-integration.md](starkernel-integration.md)** - Kernel Details
|
||||
**What:** StarKernel-specific HAL implementation and boot sequence
|
||||
**Who:** Kernel developers building StarKernel
|
||||
**Why read:** Understand UEFI boot, freestanding C, hardware initialization
|
||||
|
||||
**Key sections:**
|
||||
- StarKernel architecture (boot sequence)
|
||||
- Directory structure (`src/platform/kernel/`)
|
||||
- Boot sequence detail (UEFI → StarKernel → VM)
|
||||
- HAL implementation details (time, interrupts, memory, console, CPU)
|
||||
- Build system (freestanding toolchain, linker script)
|
||||
- Testing on QEMU/OVMF
|
||||
- Debugging techniques
|
||||
- Roadmap to `ok` prompt
|
||||
|
||||
**Includes:**
|
||||
- Complete UEFI loader implementation
|
||||
- Kernel entry point
|
||||
- Hardware initialization sequence
|
||||
- QEMU testing guide
|
||||
- Debugging strategies
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### For Different Roles
|
||||
|
||||
**I'm a VM developer:**
|
||||
- Read: `overview.md`, `interfaces.md`
|
||||
- Use HAL functions in VM code
|
||||
- Never call platform-specific APIs directly
|
||||
|
||||
**I'm adding a new platform:**
|
||||
- Read: `overview.md`, `interfaces.md`, `platform-implementations.md`
|
||||
- Implement all HAL interfaces for your platform
|
||||
- Test against VM test suite (936+ tests must pass)
|
||||
|
||||
**I'm migrating existing code to HAL:**
|
||||
- Read: `migration-plan.md`
|
||||
- Follow 7-phase incremental approach
|
||||
- Test after each phase
|
||||
|
||||
**I'm building StarKernel:**
|
||||
- Read: All documents, especially `starkernel-integration.md`
|
||||
- Start with UEFI boot + serial output
|
||||
- Build incrementally to `ok` prompt
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### HAL Principles
|
||||
|
||||
1. **VM Purity:** VM code is platform-agnostic, never knows which platform it's on
|
||||
2. **Contract-First:** HAL interfaces are contracts with precise semantics
|
||||
3. **Testability:** Develop/test on Linux, deploy on kernel
|
||||
4. **Zero Overhead:** HAL inlines to direct hardware access when optimized
|
||||
5. **Fail-Fast:** Validate platform assumptions at init, not during execution
|
||||
|
||||
### Success Criteria
|
||||
|
||||
The HAL is successful if:
|
||||
- ✅ VM core has zero platform-specific code
|
||||
- ✅ All 936+ tests pass on all platforms
|
||||
- ✅ 0% algorithmic variance maintained
|
||||
- ✅ No measurable performance regression
|
||||
- ✅ StarKernel boots to `ok` prompt
|
||||
- ✅ Physics subsystems work identically on all platforms
|
||||
|
||||
---
|
||||
|
||||
## Document Status
|
||||
|
||||
| Document | Status | Last Updated |
|
||||
|----------|--------|--------------|
|
||||
| overview.md | ✅ Complete | 2025-12-14 |
|
||||
| interfaces.md | ✅ Complete | 2025-12-14 |
|
||||
| platform-implementations.md | ✅ Complete | 2025-12-14 |
|
||||
| migration-plan.md | ✅ Complete | 2025-12-14 |
|
||||
| starkernel-integration.md | ✅ Complete | 2025-12-14 |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate (HAL Migration)
|
||||
1. Review and approve HAL interface specifications
|
||||
2. Execute migration plan Phase 1 (define interfaces)
|
||||
3. Execute migration plan Phase 2 (implement Linux HAL)
|
||||
4. Continue through Phase 7 (validation)
|
||||
|
||||
### Near-Term (StarKernel)
|
||||
1. Implement UEFI boot loader
|
||||
2. Implement kernel HAL subsystems
|
||||
3. Boot to `ok` prompt on QEMU
|
||||
4. Validate physics subsystems on bare metal
|
||||
|
||||
### Long-Term (StarshipOS)
|
||||
1. Add storage drivers (AHCI, NVMe)
|
||||
2. Add networking stack (TCP/IP)
|
||||
3. Implement process model (Forth tasks)
|
||||
4. Build device model (block/net/char)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
### StarForth Documentation
|
||||
- `docs/CLAUDE.md` - Project overview and build instructions
|
||||
- `docs/03-architecture/heartbeat-system/` - Heartbeat subsystem details
|
||||
- `docs/FEEDBACK_LOOPS.md` - Physics feedback loops
|
||||
- `README.md` - Project quick start
|
||||
|
||||
### External Resources
|
||||
- [UEFI Specification](https://uefi.org/specifications)
|
||||
- [GNU-EFI](https://sourceforge.net/projects/gnu-efi/)
|
||||
- [OSDev Wiki](https://wiki.osdev.org/)
|
||||
- [Intel Software Developer Manual](https://www.intel.com/sdm)
|
||||
- [ACPI Specification](https://uefi.org/acpi)
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
When updating HAL documentation:
|
||||
|
||||
1. **Keep documents synchronized** - Changes to interfaces require updates to implementation guides
|
||||
2. **Maintain code examples** - Examples must compile and work
|
||||
3. **Update this README** - Reflect new sections or document reorganization
|
||||
4. **Version documentation** - Note "Last Updated" dates
|
||||
5. **Test instructions** - Verify all commands and code snippets work
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
For questions about HAL architecture or StarKernel implementation, see:
|
||||
- GitHub Issues: https://github.com/anthropics/starforth/issues (if public)
|
||||
- Project maintainer: (contact info)
|
||||
- Documentation feedback: (preferred method)
|
||||
|
||||
---
|
||||
|
||||
*The HAL is not just a kernel bootstrapping tool—it's the architectural foundation for StarForth → StarKernel → StarshipOS.*
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,145 +0,0 @@
|
||||
<!-- Moved from docs/03-architecture/physics-engine/metrics-and-knobs.md to docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
# StarForth Metrics & Knobs: GAPS ONLY
|
||||
|
||||
## What's NOT Wired (Things to Add)
|
||||
|
||||
### DEAD CODE / NEVER CALLED
|
||||
|
||||
| What | Location | Status | Comment |
|
||||
|------|----------|--------|---------|
|
||||
| Bucket reordering | `physics_hotwords_cache.c:201-215` | Defined but NEVER CALLED | Bubble sort exists but no automatic trigger. Is this dead code or forgotten? |
|
||||
|
||||
---
|
||||
|
||||
### STACK METRICS (ZERO COLLECTION)
|
||||
|
||||
| Metric | File | Missing Since | Impact | Knob Needed |
|
||||
|--------|------|---|---|---|
|
||||
| Data stack peak depth | `stack_management.c` | Day 1 | Can't tell if workload needs larger stack | STACK_SIZE tuning blind |
|
||||
| Return stack peak depth | `stack_management.c` | Day 1 | Can't measure colon definition nesting | Tail-call optimization impossible |
|
||||
| Underflow attempts | `arithmetic_words.c:59-62` | Day 1 | Can't detect fragile code paths | Could optimize checks if zero underflows observed |
|
||||
| Overflow attempts | `arithmetic_words.c` | Day 1 | Can't detect stack exhaustion | Early warning system missing |
|
||||
|
||||
---
|
||||
|
||||
### DICTIONARY METRICS (ZERO VISIBILITY)
|
||||
|
||||
| Metric | File | Missing Since | Impact | Why Matters |
|
||||
|--------|------|---|---|---|
|
||||
| Bucket load histogram | `vm.c: dict lookup` | Day 1 | First-char bucketing (26 buckets) may be unbalanced | Affects lookup latency, collision clustering |
|
||||
| Dictionary growth rate | `memory_management.c` | Day 1 | No visibility into `here` pointer velocity | Can't predict "dictionary full" events |
|
||||
| FORGET usage frequency | `dictionary_words.c` | Day 1 | No trace of word deletion patterns | Fragmentation unknown |
|
||||
| Lookup failure rate | `vm.c` | Day 1 | How often is a word not found? | Error path frequency unknown |
|
||||
| Word name length distribution | `vm.c` | Day 1 | Average name length unknown | Affects memory efficiency |
|
||||
|
||||
---
|
||||
|
||||
### BLOCK I/O METRICS (COMPLETELY DARK)
|
||||
|
||||
| Metric | File | Missing Since | Impact | Phase |
|
||||
|--------|------|---|---|---|
|
||||
| Block read frequency | `block_subsystem.c` | Day 1 | How often is BLOCK called? | DoE phase 1 |
|
||||
| Block write frequency | `block_subsystem.c` | Day 1 | How often is UPDATE/FLUSH called? | DoE phase 1 |
|
||||
| Writeback frequency | `block_subsystem.c:198-200` | Day 1 | When are dirty blocks flushed? | DoE phase 1 |
|
||||
| Cache hit rate (disk) | `block_subsystem.c` | Day 1 | Blocks served from RAM cache % | DoE phase 1 |
|
||||
| Dirty block ratio | `block_subsystem.c` | Day 1 | Blocks pending flush at time T | DoE phase 1 |
|
||||
| I/O latency | `block_subsystem.c` | Day 1 | Time per read/write operation | DoE phase 2 |
|
||||
| Fragmentation ratio | `block_subsystem.c` | Day 1 | Gaps in allocated blocks | DoE phase 2 |
|
||||
|
||||
---
|
||||
|
||||
### PER-WORD EXECUTION METRICS
|
||||
|
||||
| Metric | File | Missing Since | Impact | Use Case |
|
||||
|--------|------|---|---|---|
|
||||
| Per-word execution frequency | `vm.c: inner loop` | Day 1 | Which words are actually hot? | Profiling, hotspot detection |
|
||||
| Per-word latency distribution | `vm.c` | Day 1 | Median/P99 time per word | Performance regression detection |
|
||||
| Word category breakdown | `word_source/*.c` | Day 1 | Arithmetic vs. Stack vs. Control dominance | Workload characterization |
|
||||
| Colon vs. native ratio | `vm.c` | Day 1 | User-defined word execution frequency | Code complexity analysis |
|
||||
|
||||
---
|
||||
|
||||
### HEAT DYNAMICS (PHASE 2 NOT ACTIVE)
|
||||
|
||||
| Metric | File | Status | Comment |
|
||||
|--------|------|--------|---------|
|
||||
| Heat decay trace | `physics_metadata.c: TODO` | Phase 2 placeholder | Need to measure if decay causes pattern loss |
|
||||
| Heat percentile distribution | `physics_metadata.c` | Not updating dynamic | Stored but never dynamically recalculated |
|
||||
| Heat concentration ratio | `physics_metadata.c` | Not tracked | (Top 10 words heat) / (total heat) |
|
||||
| Heat velocity | `physics_metadata.c` | Not tracked | Rate of heat change per unit time |
|
||||
| Heat plateau detection | `physics_metadata.c` | Not tracked | When does word heat level off? |
|
||||
|
||||
---
|
||||
|
||||
### PIPELINING METRICS (PHASE 1 INSTRUMENTATION, NOT USED)
|
||||
|
||||
| Metric | File | Status | Phase 2 Use |
|
||||
|--------|------|--------|---|
|
||||
| Prediction accuracy by depth | `physics_pipelining_metrics.c` | Not measured | Binary chop TRANSITION_WINDOW_SIZE |
|
||||
| Context transition frequency | `physics_pipelining_metrics.c` | Counted but not reported | Validate context patterns |
|
||||
| Speculation ROI histogram | `physics_pipelining_metrics.c` | Not aggregated | Tune SPECULATION_THRESHOLD |
|
||||
| Misprediction cost (actual) | `physics_pipelining_metrics.c` | Measured but not validated | Calibrate cost model |
|
||||
| Pipeline stall reduction | `physics_pipelining_metrics.c` | Not measured | Throughput impact unknown |
|
||||
|
||||
---
|
||||
|
||||
### CACHE POLLUTION & CYCLES
|
||||
|
||||
| Metric | File | Missing Since | Impact |
|
||||
|--------|------|---|---|
|
||||
| Cache eviction/re-promotion cycles | `physics_hotwords_cache.c` | Day 1 | Are we thrashing? |
|
||||
| False negatives (words evicted before promotion) | `physics_hotwords_cache.c` | Day 1 | Should promotion threshold be lower? |
|
||||
| Cache eviction candidate value | `physics_hotwords_cache.c` | Day 1 | Was LRU the right choice? |
|
||||
| Bucket scan depth (position of hit) | `physics_hotwords_cache.c` | Day 1 | Is bucket order actually helping? |
|
||||
| Promotion wait time | `physics_hotwords_cache.c` | Day 1 | How long does word stay in bucket before cache? |
|
||||
|
||||
---
|
||||
|
||||
## Priority for "Twisting the Dragon's Tail"
|
||||
|
||||
### 🔴 **CRITICAL (Do First)**
|
||||
1. **Stack peak depth** - 5 minutes to add, massive insight
|
||||
2. **Block I/O metrics** - Writeback behavior unknown (could be performance killer)
|
||||
3. **Dictionary bucket load** - Unbalanced bucketing = latency tail
|
||||
|
||||
### 🟠 **HIGH (Phase 1 DoE)**
|
||||
4. **Per-word execution frequency** - Validation for cache/window decisions
|
||||
5. **Heat decay trace** - Validate Phase 2 feature before enabling
|
||||
6. **Block I/O hit rate** - Complete the I/O picture
|
||||
|
||||
### 🟡 **MEDIUM (Phase 2 DoE)**
|
||||
7. **Pipelining accuracy by depth** - Input to window size binary chop
|
||||
8. **Colon definition nesting depth** - Tail-call optimization opportunities
|
||||
9. **Dictionary growth velocity** - Predict "full" events
|
||||
|
||||
### 🟢 **NICE-TO-HAVE (Phase 3)**
|
||||
10. Heat concentration ratio
|
||||
11. Word category breakdown
|
||||
12. Speculation ROI histogram
|
||||
|
||||
---
|
||||
|
||||
## Implementation Effort Estimate
|
||||
|
||||
| Category | Files | LOC | Time | Priority |
|
||||
|----------|-------|-----|------|----------|
|
||||
| Stack metrics | stack_management.c, vm.h | ~30 | 30 min | 🔴 |
|
||||
| Dictionary metrics | vm.c, memory_management.c, vm.h | ~50 | 45 min | 🔴 |
|
||||
| Block I/O metrics | block_subsystem.c, vm.h | ~80 | 1 hr | 🔴 |
|
||||
| Per-word metrics | vm.c, physics_metadata.c, vm.h | ~100 | 1.5 hr | 🟠 |
|
||||
| Heat dynamics | physics_metadata.c, vm.h | ~60 | 1 hr | 🟠 |
|
||||
| Pipelining accuracy | physics_pipelining_metrics.c, vm.h | ~40 | 45 min | 🟡 |
|
||||
|
||||
---
|
||||
|
||||
## Bucket Reordering Mystery
|
||||
|
||||
**File**: `physics_hotwords_cache.c:201-215`
|
||||
**Code**: `hotwords_bucket_reorder()` - bubble sort by execution_heat
|
||||
**Status**: Function defined but **NEVER CALLED** from lookup path
|
||||
**Question**: Is this dead code or forgot to hook it?
|
||||
|
||||
**If enabled, metrics needed:**
|
||||
- Reorder frequency
|
||||
- Cost (bubble sort latency)
|
||||
- Benefit (does reordering actually improve hit latency?)
|
||||
@@ -1,220 +0,0 @@
|
||||
<!-- Moved from docs/03-architecture/physics-engine/steady-state-machine.md to docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Conceptual precursor to the L8 Jacquard mode-selector
|
||||
> system; it never mentions Jacquard/L8, the attractor buckets, or the six named modes, and
|
||||
> was never reconciled with the implemented `ssm_jacquard.c` system. The canonical current
|
||||
> reference for the physics/feedback model is `feedback-loops.md`. Kept for historical record.
|
||||
|
||||
# 1. Introduction
|
||||
|
||||
A Steady State Machine (SSM) is a novel computational model in which the system’s operational state is defined not by discrete symbolic transitions, but by convergence to an optimal runtime equilibrium.
|
||||
|
||||
Unlike traditional models such as Finite State Machines (FSMs), Pushdown Automata, or Turing Machines — where “state” is explicit and symbolic — a Steady State Machine derives its behavior from continuous thermodynamic variables such as:
|
||||
|
||||
* execution_heat
|
||||
|
||||
* entropy (diversity)
|
||||
|
||||
* pipeline readiness
|
||||
|
||||
* heat decay
|
||||
|
||||
* steady-state slope
|
||||
|
||||
* localized temperature gradients
|
||||
|
||||
* adaptive strategy selection
|
||||
|
||||
An SSM observes itself, adapts, and settles into stable performance basins called steady states.
|
||||
|
||||
This makes the Steady State Machine the first computational model where the attractor defines the machine, not the symbol.
|
||||
|
||||
# 2. Core Definition
|
||||
Definition 1 — Steady State Machine
|
||||
|
||||
> A Steady State Machine is a computational system defined by:
|
||||
|
||||
A set of internal physical metrics
|
||||
|
||||
* 𝐻 = execution_heats
|
||||
|
||||
* 𝐸 = entropy/diversity measures
|
||||
|
||||
* 𝑃 = pipeline activation thresholds
|
||||
|
||||
* Θ = heat decay profile
|
||||
|
||||
* 𝑊 = sliding execution window
|
||||
|
||||
A set of adaptive policies
|
||||
|
||||
* lookup strategies
|
||||
|
||||
* caching regimes
|
||||
|
||||
* bucket reorganizations
|
||||
|
||||
* pipeline decisions
|
||||
|
||||
* inference-based mode switches
|
||||
|
||||
* A state-space composed of attractor basins, not symbolic states
|
||||
|
||||
* steady attractor
|
||||
|
||||
* quasi-steady attractor
|
||||
|
||||
* transient attractor
|
||||
|
||||
* chaotic attractor
|
||||
|
||||
* A governing dynamic
|
||||
|
||||
|
||||
### 𝑀𝑡+1=𝑓(𝑀𝑡,Δ𝐻,Δ𝑊,Δ𝐸) where 𝑓 pushes the machine toward a stable basin.
|
||||
|
||||
The machine is defined by its convergence behavior, not its instruction sequence.
|
||||
|
||||
# 3. The Fundamental Insight
|
||||
|
||||
In an SSM, performance is the state.
|
||||
|
||||
The system is constantly measuring:
|
||||
|
||||
* how hot words are
|
||||
|
||||
* how often patterns recur
|
||||
|
||||
* how pipeline-able a sequence is
|
||||
|
||||
* how diverse the window is
|
||||
|
||||
* how much the dictionary should reorganize
|
||||
|
||||
And as these stabilize, the machine settles into a steady state — a self-maintaining optimal regime.
|
||||
|
||||
This regime is preserved until the environment changes (e.g., new workloads, diversity spikes), at which point the SSM moves into a transient or chaotic regime and eventually finds a new equilibrium.
|
||||
|
||||
# 4. Phases of a Steady State Machine
|
||||
## 1. Transient Phase
|
||||
|
||||
- System warms up
|
||||
|
||||
- Execution patterns are sporadic
|
||||
|
||||
- Heat gradients are noisy
|
||||
|
||||
- Pipeline inactive or unstable
|
||||
|
||||
## 2. Quasi-Steady Phase
|
||||
|
||||
- Some patterns emerge
|
||||
|
||||
- Lookups begin to bias
|
||||
|
||||
- Hot words form local attractors
|
||||
|
||||
- Dictionary reorders stabilize
|
||||
|
||||
## 3. True Steady State
|
||||
|
||||
- Heat surface smooth
|
||||
|
||||
- Pipeline active
|
||||
|
||||
- Diversity window predictable
|
||||
|
||||
- Lookups converge to optimal
|
||||
|
||||
- Runtime > baseline VM
|
||||
|
||||
- System remains stable unless perturbed
|
||||
|
||||
## 4. Chaotic/Disruption Phase
|
||||
|
||||
### Triggered by:
|
||||
|
||||
- major workload shift
|
||||
|
||||
- dictionary mutation
|
||||
|
||||
- extreme entropy spike
|
||||
|
||||
- cold-cache shock
|
||||
|
||||
- SSM falls out of equilibrium temporarily.
|
||||
|
||||
## 5. Axioms of Steady State Machines
|
||||
>Axiom 1 — Convergence
|
||||
Every sustained workload induces the SSM to converge toward a stable attractor unless external entropy forces divergence.
|
||||
|
||||
>Axiom 2 — Locality of Heat
|
||||
Execution heat reflects both locality and temporal relevance. Locality produces stability.
|
||||
|
||||
>Axiom 3 — Adaptive Reordering
|
||||
Reordering is not symbolic mutation; it is thermodynamic self-optimization.
|
||||
|
||||
>Axiom 4 — Stability Maximizes Throughput
|
||||
The steady state is always faster than the cold state, and usually faster than the naive baseline VM.
|
||||
|
||||
>Axiom 5 — Perturbation Response
|
||||
When disrupted, the SSM seeks a new steady state; it does not thrash indefinitely.
|
||||
|
||||
## 6. Relationship to Other Computational Models
|
||||
>FSM vs SSM
|
||||
FSM: discrete symbolic states
|
||||
SSM: emergent attractors in thermal space
|
||||
|
||||
>Turing Machine vs SSM
|
||||
TM: behavior defined by tape symbols and transitions
|
||||
SSM: behavior defined by adaptation toward equilibrium
|
||||
|
||||
>Markov Chain vs SSM
|
||||
MC: probabilistic transitions between explicit states
|
||||
SSM: deterministic drift toward stable basins, driven by observation
|
||||
|
||||
>Neural Network vs SSM
|
||||
NN: learns weights
|
||||
SSM: reorganizes runtime structures, not parameters
|
||||
|
||||
## 7. Why This Breaks New Ground
|
||||
|
||||
### A Steady State Machine is the first:
|
||||
|
||||
- runtime-thermodynamic computing model
|
||||
|
||||
- adaptive VM with convergence properties
|
||||
|
||||
- load-dependent reordering machine
|
||||
|
||||
- self-optimizing dictionary machine
|
||||
|
||||
- phase-shifting execution system
|
||||
|
||||
- state-machine whose state is emergent, not explicit
|
||||
|
||||
- This is a fundamental new category of computation.
|
||||
|
||||
## 8. Canonical Example: StarForth
|
||||
|
||||
### StarForth implements the first real SSM with:
|
||||
|
||||
- execution_heat
|
||||
|
||||
- rolling diversity windows
|
||||
|
||||
- phase-based lookup strategies
|
||||
|
||||
- adaptive dictionary ordering
|
||||
|
||||
- pipeline activation
|
||||
|
||||
- DOE-calibrated inference loop
|
||||
|
||||
- background physics monitor
|
||||
|
||||
- It is, quite literally, the reference implementation.
|
||||
|
||||
## 9. Formal Summary Statement
|
||||
|
||||
>A Steady State Machine (SSM) is a computational system in which the operational state is defined by attractor convergence in thermodynamic runtime space rather than by discrete symbolic transitions. An SSM continuously measures workload characteristics, adjusts internal structures, and stabilizes into performance-optimized steady states. When perturbed, it transitions through transient or chaotic phases before finding a new equilibrium. This model defines a new class of adaptive computational systems with properties distinct from finite state machines, pushdown automata, and Turing Machines.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- Moved from docs/03-architecture/word-acl/DESIGN.md to docs/working/architecture/03-architecture/word-acl/DESIGN.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
<!-- Moved from docs/reference/word-acl/DESIGN.md to docs/working/architecture/03-architecture/word-acl/DESIGN.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
# Word-Level ACL System
|
||||
|
||||
**Status:** Implemented through Phase 6 — Phase 7 (LithosAnanke parity) remaining
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -34,7 +34,7 @@ source material that `docs/formal/scraps/architecture/` is generated from.
|
||||
|
||||
## See also
|
||||
|
||||
- [`docs/03-architecture/README.md`](../../03-architecture/README.md) — the
|
||||
- [`docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md`](../../03-architecture/README.md) — the
|
||||
*binding-constraint* Tripod/ACL docs, distinct from this design-notes tree.
|
||||
- [`docs/formal/scraps/README.md`](../../formal/scraps/README.md) — the
|
||||
press-ready fragment tier this material feeds.
|
||||
|
||||
@@ -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