FractalSemantics - FractalSemantics Validation Experiments

• A complete validation suite for the FractalSemantics 8-dimensional addressing system

🔬 Recent Discovery (Nov 2025): EXP-11 testing confirms 8 dimensions are optimal and superior to the original 7-dimension design. See !5 for details. EXP-01 validation results remain valid as they are dimension-count agnostic. FractalSemantics implementation complete.

What is FractalSemantics?

FractalSemantics is a research package containing 21 validation experiments that prove the FractalSemantics 8-dimensional addressing system works at scale. FractalSemantics expands FractalSemantics from a 7D to an 8-dimensional coordinate system for uniquely addressing data in fractal information spaces.

The 8 Dimensions:

• Realm - Domain classification (data, narrative, system, etc.)
• Lineage - Generation from LUCA (Last Universal Common Ancestor)
• Temperature - Thermal activity level (0.0 to abs(velocity) * density)
• Adjacency - Relational neighbors (graph connections)
• Horizon - Lifecycle stage (genesis, emergence, peak, decay, crystallization)
• Resonance - Charge/alignment (-1.0 to 1.0)
• Velocity - Rate of change
• Density - Compression distance (0.0 to 1.0)
• Alignment - Value based on alignment map

The 21 Experiments

Core Addressing System (EXP-01 to EXP-12)

Exp	Name	Tests	Status
EXP-01	Geometric Collisions	Zero collisions over 3D	[Success] PASS
EXP-02	Retrieval Efficiency	Sub-millisecond retrieval	[Success] PASS
EXP-03	Coordinate Space Entropy	Entropy contribution per dimension	[Success] PASS
EXP-04	Fractal Scaling	Consistency at 1M+ scale	[Success] PASS
EXP-05	Compression/Expansion	Lossless encoding	[Success] PASS
EXP-06	Entanglement Detection	Semantic relationships	[Success] PASS
EXP-07	LUCA Bootstrap	Full system reconstruction	[Success] PASS
EXP-08	Self-Organizing Memory	Memory network formation	[Success] PASS
EXP-09	Memory Pressure	Performance under load	[Success] PASS
EXP-10	Multi-Dimensional Query	Query optimization across dimensions	[Success] PASS
EXP-11	Dimension Cardinality	Optimal dimension count analysis	[Success] PASS
EXP-11b	Dimension Stress Test	Extreme dimension testing	[Success] PASS
EXP-12	Benchmark Comparison	FractalSemantics vs. common systems	[Success] PASS

Advanced Physics & Thermodynamics (EXP-13 to EXP-21)

Exp	Name	Tests	Status
EXP-13	Fractal Gravity	Gravity simulation without falloff	[Success] PASS
EXP-14	Atomic Fractal Mapping	Atomic structure representation	[Success] PASS
EXP-15	Topological Conservation	Topological properties preservation	[Success] PASS
EXP-16	Hierarchical Distance Mapping	Distance hierarchy validation	[Success] PASS
EXP-17	Thermodynamic Validation	Thermodynamic laws compliance	[Success] PASS
EXP-18	Falloff Thermodynamics	Falloff behavior analysis	[Success] PASS
EXP-19	Orbital Equivalence	Orbital mechanics equivalence	[Success] PASS
EXP-20	Vector Field Derivation	Vector field from fractal hierarchy	[Success] PASS
EXP-21	Earth-Moon-Sun Critical Scaling	Hierarchical scaling under orbital dynamics	[Success] PASS

Experiment Descriptions

Core Addressing System

EXP-01: Geometric Collision Resistance Tests that FractalSemantics coordinates achieve collision resistance through semantic differentiation rather than coordinate space geometry. Demonstrates that expressivity emerges from deterministic coordinate assignment.

EXP-02: Retrieval Efficiency Validates sub-millisecond retrieval performance for FractalSemantics addressing system, ensuring practical usability for real-time applications.

EXP-03: Coordinate Space Entropy Measures entropy contribution per dimension to validate that each dimension adds meaningful information content to the addressing system.

EXP-04: Fractal Scaling Tests whether FractalSemantics addressing maintains consistency and zero collisions when scaled from 1K - 10K - 100K - 1M data points, verifying the "fractal" property of self-similar behavior at all scales.

EXP-05: Compression/Expansion Validates lossless encoding capabilities of the FractalSemantics coordinate system, ensuring data integrity during compression and expansion operations.

EXP-06: Entanglement Detection Tests the system's ability to detect and handle semantic relationships between different data entities within the fractal coordinate space.

EXP-07: LUCA Bootstrap Validates the full system reconstruction capability from the Last Universal Common Ancestor (LUCA) concept, ensuring the system can bootstrap from fundamental principles.

EXP-08: Self-Organizing Memory Tests the formation and organization of memory networks within the FractalSemantics framework, demonstrating emergent organizational properties.

EXP-09: Memory Pressure Evaluates system performance under memory load conditions, ensuring robustness in resource-constrained environments.

EXP-10: Multi-Dimensional Query Optimization Tests query performance and optimization across multiple dimensions simultaneously, validating the system's ability to handle complex multi-dimensional queries efficiently.

EXP-11: Dimension Cardinality Analyzes optimal dimension count for the addressing system, determining the mathematical sweet spot for dimensionality.

EXP-11b: Dimension Stress Test Performs extreme testing of dimensionality limits to understand system behavior under stress conditions.

EXP-12: Benchmark Comparison Compares FractalSemantics performance against common addressing systems to establish relative advantages and disadvantages.

Advanced Physics & Thermodynamics

EXP-13: Fractal Gravity Simulates gravitational effects within the fractal coordinate system without traditional falloff behavior, exploring alternative physics models.

EXP-14: Atomic Fractal Mapping Tests the representation of atomic structures within the fractal framework, validating the system's ability to model complex physical systems.

EXP-15: Topological Conservation Validates that topological properties are preserved across fractal transformations, ensuring mathematical consistency.

EXP-16: Hierarchical Distance Mapping Tests the validation of distance hierarchies within the fractal system, ensuring proper spatial relationships are maintained.

EXP-17: Thermodynamic Validation Confirms that the fractal system complies with fundamental thermodynamic laws, ensuring physical plausibility.

EXP-18: Falloff Thermodynamics Analyzes falloff behavior in thermodynamic contexts within the fractal framework, exploring energy distribution patterns.

EXP-19: Orbital Equivalence Tests the equivalence of orbital mechanics within the fractal system compared to traditional physics models.

EXP-20: Vector Field Derivation Derives vector fields from fractal hierarchy, demonstrating that directional force vectors emerge naturally from hierarchical relationships.

EXP-21: Earth-Moon-Sun Critical Scaling Stress-tests hierarchical scaling claims against a constrained orbital scenario and records scientifically valid positive/negative outcomes independent of runtime status.

The GUI Application

- Interactive Web Interface

FractalSemantics includes a comprehensive Streamlit-based GUI application that provides:

• 📊 Real-time Experiment Monitoring - Watch experiments run with live progress bars and status updates
• 📈 Advanced Data Visualization - Interactive Plotly charts for all experiment results
• 📚 Educational Content - Mathematical explanations and learning materials for each experiment
• 🔬 Batch Experiment Management - Configure and run multiple experiments simultaneously
• ⚙️ Export Options - Export results to JSON, CSV, and PDF formats
• - Performance Analytics - Detailed performance metrics and system health monitoring

Key GUI Features

Dashboard Overview

• Experiment Progress: Real-time progress tracking with percentage completion
• Performance Metrics: Success rates, execution times, and resource usage
• System Health: CPU, memory, and disk space monitoring
• Results Summary: Quick overview of all experiment outcomes

Interactive Visualizations

• Success Rate Charts: Bar charts showing experiment success by type
• Performance Analysis: Scatter plots of execution times vs. experiment complexity
• Progress Timeline: Line charts showing real-time progress updates
• Educational Content: Expandable sections with mathematical explanations

Experiment Control

• Multi-Selection: Choose which experiments to run from the full suite
• Configuration Options: Quick mode, parallel execution, and feature level settings
• Real-time Feedback: Live output display and progress updates
• Batch Management: Run experiments in parallel or sequentially

Educational Interface

• Mathematical Foundations: Detailed explanations of fractal geometry and coordinate systems
• Experiment Documentation: Step-by-step guides for each validation experiment
• Real-World Applications: Examples of how FractalSemantics applies to data management
• Interactive Learning: Hands-on exploration of fractal concepts

Launching the GUI

# Install GUI dependencies
pip install -r gui_requirements.txt

# Launch the GUI application
python launch_gui.py

# Or run directly with Streamlit
streamlit run gui_app.py

GUI Architecture

The GUI is built using modern web technologies:

• Frontend: Streamlit with custom CSS styling and Plotly visualizations
• Backend: Python experiment runner with real-time progress communication
• Data Flow: JSON-based communication between experiment modules and GUI
• State Management: Streamlit session state for persistent data across interactions
• Progress System: Custom progress reporter for real-time updates

Screenshots and Examples

The GUI provides stunning visualizations of experiment results, including:

• 3D Fractal Visualizations: Interactive plots showing coordinate space distributions
• Performance Dashboards: Real-time charts of experiment execution metrics
• Educational Diagrams: Mathematical concepts visualized for better understanding
• Progress Indicators: Beautiful progress bars and status indicators

For detailed GUI documentation, see GUI_README.md.

EXP-01: Address Uniqueness Test

Status: [Success] PASS (Publication Ready)
Confidence: 99.9%
Sample Size: 10,000 bit-chains

Quick Summary

EXP-01 has been rewritten to illustrate how increasing the number of dimensions naturally eliminates concerns of collision. While our SHA-256 hashing of canonical serialization already guarantees zero collisions, this test proves that SHA256 is a security choice and not our crutch for collision-free addressing.

Key Results

• Total Bit-Chains Tested: 10,000
• Unique Addresses: 10,000
• Collisions Detected: 0
• Collision Rate: 0.0%
• Success Rate: 100% (10/10 iterations passed)

Documentation

• Experiment implementation: fractalsemantics/exp01_geometric_collision.py
• Most recent artifacts: results/exp01_*.json
• Suite analysis report: comprehensive_experiment_analysis.txt

Running EXP-01

# Run EXP-01 only
python fractalsemantics/experiment_runner.py EXP-01 --full --format=text

# Fast EXP-01 iteration
python fractalsemantics/experiment_runner.py EXP-01 --quick --format=text

# Disable persisted artifacts (terminal output only)
python fractalsemantics/experiment_runner.py EXP-01 --quick --softcopy=false --format=text

Citation

If you use EXP-01 results in your research, please cite:

@software{fractalsemantics_exp01,
  title = {FractalSemantics EXP-01: Address Uniqueness Test},
  author = {[Authors]},
  year = {2024},
  version = {1.0.0},
  url = {https://gitlab.com/tiny-walnut-games/fractalsemantics}
}

Quick Start

Public CLI/API Index

For a GitBook-ready documentation archive (CLI + API + operations), see:

• docs/gitbook-archive/README.md
• docs/gitbook-archive/SUMMARY.md

Command Line Interface

# Install dependencies
pip install -r requirements.txt

# Install the package in development mode
pip install -e .

# Run all experiments
python fractalsemantics/experiment_runner.py --all --full --format=text

# Run all experiments in explicit parallel mode
python fractalsemantics/experiment_runner.py --all --full --parallel --format=text

# Run targeted experiments
python fractalsemantics/experiment_runner.py EXP-01 EXP-03 EXP-21 --serial --full --format=text

# Reproducibility reruns
python fractalsemantics/experiment_runner.py EXP-13 --full --repro-runs=3 --format=text

# Run analysis from cached results
python comprehensive_experiment_analysis.py

# Refresh + analyze with argument pass-through to runner
python comprehensive_experiment_analysis.py --refresh --all --full --serial --format=text

Analysis CLI Options

comprehensive_experiment_analysis.py analyzes cached results by default and supports optional refresh/wipe workflows.

# Cached analysis only (no reruns)
python comprehensive_experiment_analysis.py

# Refresh from runner before analysis (arguments after --refresh are passed through)
python comprehensive_experiment_analysis.py --refresh --all --full --serial --format=text

# Wipe history first (prompts to archive vs delete), then refresh and analyze
python comprehensive_experiment_analysis.py --wipe-history --refresh --all --full --serial --format=text

# Nuclear mode: delete archive store and force-delete history (no archive prompt)
python comprehensive_experiment_analysis.py --wipe-archive --wipe-history --refresh --all --full --serial --format=text

# Show analysis CLI help
python comprehensive_experiment_analysis.py --help

Key behavior:

• --refresh: runs fractalsemantics/experiment_runner.py first, then performs analysis.
• --wipe-history: targets results/*.json, results/figures/*, and results/reports/* before refresh/analysis.
• --wipe-archive: deletes results/archive and forces delete mode for --wipe-history.
• Without --refresh, extra runner flags are ignored by the analysis script.

GUI Application (Recommended)

For an interactive experience with real-time visualization and educational content:

# Install GUI dependencies
pip install -r gui_requirements.txt

# Launch the GUI application
python launch_gui.py

# Or run directly with Streamlit
streamlit run gui_app.py

GUI Features:

• 📊 Interactive dashboard with real-time experiment monitoring
• 📈 Advanced data visualizations with Plotly charts
• 📚 Educational content and mathematical explanations
• 🔬 Batch experiment management and configuration
• ⚙️ Export options (JSON, CSV, PDF)
• • Real-time progress tracking and performance metrics

For detailed GUI documentation, see GUI_README.md.

ARM/Raspberry Pi Setup

FractalSemantics works on ARM architectures, but PyTorch installation may require special handling:

# For Raspberry Pi (ARM64) - Install PyTorch first
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# Then install other dependencies
pip install -r requirements.txt
pip install -e .

# Run experiments (may be slower on ARM without GPU)
python fractalsemantics/experiment_runner.py --all --quick --format=text

ARM Considerations:

• Some experiments (EXP-08 LLM integration) may be slower without GPU acceleration
• Memory usage can be high - 4GB+ RAM recommended
• All core FractalSemantics functionality works identically across architectures

Experiment Configuration

FractalSemantics uses feature flags to configure experiments. This allows you to:

• Run experiments with different parameters without code changes
• Use environment-specific configurations (dev, ci, production)
• Ensure reproducibility by locking configuration for publication

Configuration Files

• fractalsemantics/config/experiments.toml - Default configuration for all experiments
• fractalsemantics/config/experiments.dev.toml - Development overrides (quick modes, smaller samples)
• fractalsemantics/config/experiments.ci.toml - CI/CD overrides (balanced for pipeline speed)

Using Different Environments

# Use development config (fast iteration)
export FRACTALSEMANTICS_ENV=dev
python fractalsemantics/experiment_runner.py --all --quick --format=text

# Use CI config (balanced testing)
export FRACTALSEMANTICS_ENV=ci
python fractalsemantics/experiment_runner.py --all --full --format=text

# Use production config (full validation)
export FRACTALSEMANTICS_ENV=production
python fractalsemantics/experiment_runner.py --all --full --serial --format=text

Example Configuration

# fractalsemantics/config/experiments.toml
[experiments]
enabled = ["EXP-01", "EXP-02", "EXP-03", "EXP-04", "EXP-05", 
           "EXP-06", "EXP-07", "EXP-08", "EXP-09", "EXP-10",
           "EXP-11", "EXP-12"]

[experiments.EXP-01]
name = "Address Uniqueness Test"
sample_size = 1000
iterations = 10

[experiments.EXP-04]
name = "Fractal Scaling"
quick_mode = true
scales = [1000, 10000, 100000]

Programmatic Access

from fractalsemantics.config import ExperimentConfig

config = ExperimentConfig()

# Check if experiment is enabled
if config.is_enabled("EXP-01"):
    sample_size = config.get("EXP-01", "sample_size", 1000)
    iterations = config.get("EXP-01", "iterations", 10)
    # Run experiment...

For more details, see fractalsemantics/config/feature_flags.py.

License

MIT License

Documentation Lifecycle

To keep docs useful and reduce clutter, this repository uses a simple lifecycle:

• Keep: active operational docs tied to current workflows and supported commands.
• Update: long-lived guides when flags, tools, or processes change.
• Remove: one-off fix summaries and stale status snapshots once superseded.
• Recover: rely on git history for historical context instead of preserving stale files in-tree.

Recovering Removed or Older Docs Quickly

# See deleted/renamed documentation files
git log --diff-filter=D --name-status -- "*.md"

# Trace history for a specific file path (even through renames)
git log --follow -- path/to/file.md

# View the last committed version of a removed file
git show <commit_sha>:path/to/file.md

# Search history for a phrase that existed in old docs
git log -S "search phrase" -- "*.md"

This keeps the working tree focused on current truth while preserving full project memory in commit history.