# carlsr9001/wh-falsify architecture

> Architecture diagram of the GitHub repository carlsr9001/wh-falsify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carlsr9001/wh-falsify
- Repository: https://github.com/carlsr9001/wh-falsify

## Overview

##### Project type and purpose
- This is a scientific simulation and diagnostic pipeline (“Wormhole Analog Lab”) for generating, analyzing, and visualizing synthetic traversable wormhole experiments.
- It provides a CLI entry point for running simulations, a Python package (`wormhole_proof`) implementing the core dynamics and analysis, a suite of standalone analysis scripts, and a FastAPI-based visualization server.

##### File structure
- Top-level CLI scripts:
- `run_smooth.py`, `debug_run.py`, `debug_run_default.py`
- Experiment artifacts (JSON/MD outputs) organized under `gr_suite*/`, `relativistic_suite*` directories
- `scripts/` folder: standalone analysis helpers (e.g. `gr_hotspot_report.py`, `gr_metric_analysis.py`, `run_gr_suite.py`, `run_relativistic.py`)
- `wormhole_proof/` package:
- `core/` (simulation engine, sweep, smoothing)
- `analysis/` (relativistic diagnostics)
- `wireframe/` (FastAPI server, static viewer, projection logic)
- `config.py`, `report.py`, `visualization.py`, `experiment.py`
- `tests/` for unit tests, and `requirements.txt` for dependencies

##### README for additional insights
- The wireframe server uses FastAPI to serve interactive 3D/high-D views.
- Artifacts folder is version-controlled for reproducibility.

##### Detail without over-splitting
- Logical component (CLI entry, simulation engine, analysis library, report generator, visualization service, artifact storage, tests).
- Don’t hesitate to break out submodules (e.g. `core/benchmarks`, `analysis/relativistic.py`) if they play a distinct role in your workflow.
- Keep the focus on the essential architectural elements and their interactions rather than every single file.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        style CLI fill:#f9f,stroke:#333,stroke-width:1px
        RunSmooth["run_smooth.py"]:::cli
        DebugRun["debug_run.py"]:::cli
        DebugRunDef["debug_run_default.py"]:::cli
        RunGR["run_gr_suite.py"]:::cli
        RunRel["run_relativistic.py"]:::cli
        Hotspot["gr_hotspot_report.py"]:::cli
        MetricAnalysis["gr_metric_analysis.py"]:::cli
        WindowSweep["gr_window_sweep.py"]:::cli
        HPSweep["hp_sweep.py"]:::cli
        PackMetrics["pack_gr_metrics.py"]:::cli
        PlotRel["plot_relativistic.py"]:::cli
    end

    %% Core Library
    subgraph "Core Library (wormhole_proof)"
        style Core fill:#bbf,stroke:#333,stroke-width:1px
        Config["config.py"]:::core
        Experiment["experiment.py"]:::core
        WormholeDyn["wormhole.py"]:::core
        Sweep["sweep.py"]:::core
        Smooth["wormhole_smooth.py"]:::core
        Benchmarks["benchmarks/quadratic.py"]:::core
        AnalysisMod["analysis/relativistic.py"]:::core
        Report["report.py"]:::core
        VizUtil["visualization.py"]:::core
    end

    %% Artifact Store
    subgraph "Artifact Store"
        style Data fill:#bfb,stroke:#333,stroke-width:1px
        GRSuite["gr_suite/"]:::data
        GRSuiteAbl["gr_suite_ablation/"]:::data
        RelSuite["relativistic_suite/"]:::data
        RelSuiteAbl["relativistic_suite_ablation/"]:::data
    end

    %% Visualization Service
    subgraph "Visualization Service"
        style Service fill:#bdf,stroke:#333,stroke-width:1px
        Server["wireframe/server.py (FastAPI)"]:::service
        Projection["wireframe/projection.py"]:::service
        StaticIndex["wireframe/static/index.html"]:::service
        StaticHigh["wireframe/static/highdim.html"]:::service
        Browser["Browser"]:::service
    end

    %% Tests
    subgraph "Tests"
        style Tests fill:#fbb,stroke:#333,stroke-width:1px
        TestBridge["tests/test_bridge.py"]:::tests
        TestWorm["tests/test_wormhole.py"]:::tests
    end

    %% Connections
    RunSmooth -->|invokes| Config
    DebugRun -->|invokes| Config
    DebugRunDef -->|invokes| Config
    RunGR -->|invokes| Sweep
    RunRel -->|invokes| Experiment
    RunSmooth -->|calls| WormholeDyn
    DebugRun -->|calls| WormholeDyn
    RunSmooth -->|calls| Smooth

    Config --> Experiment
    Experiment --> WormholeDyn
    WormholeDyn --> Sweep
    Sweep --> Smooth
    Smooth --> Benchmarks
    AnalysisMod -->|uses core| WormholeDyn

    Experiment -->|writes to| GRSuite
    Experiment -->|writes to| GRSuiteAbl
    Experiment -->|writes to| RelSuite
    Experiment -->|writes to| RelSuiteAbl

    Hotspot -->|reads artifacts| GRSuite
    MetricAnalysis -->|reads artifacts| GRSuite
    WindowSweep -->|reads artifacts| GRSuite
    HPSweep -->|reads artifacts| GRSuite
    PackMetrics -->|reads artifacts| GRSuite
    PlotRel -->|reads artifacts| RelSuite

    GRSuite --> Report
    RelSuite --> Report
    Report -->|generates| GRSuite
    Report -->|generates| RelSuite

    GRSuite --> Server
    RelSuite --> Server
    Server --> Projection
    Server --> StaticIndex
    Server --> StaticHigh
    Server --> Browser

    TestBridge -->|tests| WormholeDyn
    TestWorm -->|tests| WormholeDyn

    %% Click Events
    click RunSmooth "https://github.com/carlsr9001/wh-falsify/blob/main/run_smooth.py"
    click DebugRun "https://github.com/carlsr9001/wh-falsify/blob/main/debug_run.py"
    click DebugRunDef "https://github.com/carlsr9001/wh-falsify/blob/main/debug_run_default.py"
    click RunGR "https://github.com/carlsr9001/wh-falsify/blob/main/scripts/run_gr_suite.py"
    click RunRel "https://github.com/carlsr9001/wh-falsify/blob/main/scripts/run_relativistic.py"
    click Hotspot "https://github.com/carlsr9001/wh-falsify/blob/main/scripts/gr_hotspot_report.py"
    click MetricAnalysis "https://github.com/carlsr9001/wh-falsify/blob/main/scripts/gr_metric_analysis.py"
    click WindowSweep "https://github.com/carlsr9001/wh-falsify/blob/main/scripts/gr_window_sweep.py"
    click HPSweep "https://github.com/carlsr9001/wh-falsify/blob/main/scripts/hp_sweep.py"
    click PackMetrics "https://github.com/carlsr9001/wh-falsify/blob/main/scripts/pack_gr_metrics.py"
    click PlotRel "https://github.com/carlsr9001/wh-falsify/blob/main/scripts/plot_relativistic.py"
    click WormholeDyn "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/core/wormhole.py"
    click Sweep "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/core/sweep.py"
    click Smooth "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/core/wormhole_smooth.py"
    click Benchmarks "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/core/benchmarks/quadratic.py"
    click AnalysisMod "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/analysis/relativistic.py"
    click Config "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/config.py"
    click Experiment "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/experiment.py"
    click Report "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/report.py"
    click VizUtil "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/visualization.py"
    click Server "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/wireframe/server.py"
    click Projection "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/wireframe/projection.py"
    click StaticIndex "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/wireframe/static/index.html"
    click StaticHigh "https://github.com/carlsr9001/wh-falsify/blob/main/wormhole_proof/wireframe/static/highdim.html"
    click GRSuite "https://github.com/carlsr9001/wh-falsify/tree/main/gr_suite/"
    click GRSuiteAbl "https://github.com/carlsr9001/wh-falsify/tree/main/gr_suite_ablation/"
    click RelSuite "https://github.com/carlsr9001/wh-falsify/tree/main/relativistic_suite/"
    click RelSuiteAbl "https://github.com/carlsr9001/wh-falsify/tree/main/relativistic_suite_ablation/"
    click TestBridge "https://github.com/carlsr9001/wh-falsify/blob/main/tests/test_bridge.py"
    click TestWorm "https://github.com/carlsr9001/wh-falsify/blob/main/tests/test_wormhole.py"

    %% Styles
    classDef cli fill:#ffe4e1,stroke:#333,stroke-width:1px
    classDef core fill:#e0ffff,stroke:#333,stroke-width:1px
    classDef data fill:#f0fff0,stroke:#333,stroke-width:1px
    classDef service fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef tests fill:#fff0f5,stroke:#333,stroke-width:1px
```
