# tnsr-q/pqrg-theory architecture

> Architecture diagram of the GitHub repository tnsr-q/pqrg-theory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tnsr-q/pqrg-theory
- Repository: https://github.com/tnsr-q/pqrg-theory

## Overview

##### Project type and purpose
- This is a research-oriented Python project combining:
– Theoretical frameworks and derivations (in “theory/”, “calculations/”, DERIVATIONS.md)
– Numeric simulations of φ⁻¹ emergence (in “simulations/” and “Simulations/”)
– Data assets and experiment protocols (in “data/” and “experiments/”)
– Visualization pipeline (in “figs/”, generate_visuals.py, VISUALIZATIONS.md)
– Applications and demos (in “applications/”)
– Validation and testing (validate_theory.py, “tests/”)

##### File structure
- Top-level modules:
– theory/, calculations/, DERIVATIONS.md → core mathematical framework
– simulations/, Simulations/ → code and Jupyter notebooks for numerical experiments
– data/ → raw and processed CSV data plus README
– figs/, generate_visuals.py, VISUALIZATIONS.md → figure-generation scripts and gallery
– applications/ → demonstration scripts and notebooks using core code
– tests/, validate_theory.py → automated validation and unit tests
– docs/ → project documentation and whitepapers
– CI/CD: .github/workflows/generate_visuals.yml
– Dockerfile, requirements.txt
- Patterns: Modular pipeline—Theory → Calculations → Simulations → Data → Visualizations → Applications → Validation/CI.

##### README insights
- The README outlines:
– Core theory (link to theory documents)
– Simulation entry points (python simulations/phi_convergence.py)
– Visualization commands (generate_visuals.py)
– Validation step (validate_theory.py)
- Dependencies: Python, QuTiP, SymPy, plotting libraries, Docker.

##### Main components & interactions
a. Components:
1. Theory Engine
- theory/ (Markdown with equations)
- calculations/ (algorithmic derivations)
- DERIVATIONS.md
2. Simulation Engine
- simulations/ (Python scripts & notebooks implementing physics simulations)
- Simulations/ (parallel directory of specialized scripts)
3. Data Layer
- data/ (CSV files & README)
- experiments/ (protocol definitions for physical tests)
4. Visualization Pipeline
- figs/ (plot source code)
- generate_visuals.py, VISUALIZATIONS.md
5. Application/Demo Layer
- applications/ (demo scripts & notebooks for AGI oracle and ethics demos)
6. Validation & Testing
- validate_theory.py (end-to-end checks)
- tests/ (unit tests)
7. Infrastructure
- Dockerfile (containerization)
- .github/workflows/generate_visuals.yml (CI for auto-generating visuals)
- requirements.txt (Python dependencies)
b. Relationships:
– Theory Engine → drives Calculations
– Calculations + Theory → feed parameters into Simulation Engine
– Simulation Engine → outputs raw data to Data Layer
– Data Layer → consumed by Visualization Pipeline and Application/Demo Layer
– Visualization Pipeline → produces figures for docs and README
– Application/Demo Layer → leverages Simulations + Visualizations for interactive demos
– Validation & Testing → pulls from all code directories to ensure correctness
– CI/CD Infrastructure → orchestrates tests, visual generation, and Docker builds

##### Architectural patterns and principles
- Modular, staged pipeline (akin to ETL):
Extract (Theory/Calculations) → Transform (Simulations) → Load/Present (Data/Visuals)
- Clear separation of concerns: theory vs. simulation vs. visualization vs. application
- Test-driven and CI-integrated research workflows

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Theory & Calculations
    subgraph "Theory & Calculations"
        direction TB
        theory["theory/"] 
        deriv["DERIVATIONS.md"]
        calc["calculations/"]
    end

    %% Simulation Engine
    subgraph "Simulation Engine"
        direction TB
        sims1["simulations/"]
        sims2["Simulations/"]
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        data["data/"]
        experiments["experiments/"]
    end

    %% Visualization Pipeline
    subgraph "Visualization Pipeline"
        direction TB
        figs["figs/"]
        genVis["generate_visuals.py"]
        docVis["VISUALIZATIONS.md"]
    end

    %% Application/Demo Layer
    subgraph "Application/Demo Layer"
        direction TB
        apps["applications/"]
    end

    %% Validation & Testing
    subgraph "Validation & Testing"
        direction TB
        validate["validate_theory.py"]
        tests["tests/"]
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        ci[".github/workflows/generate_visuals.yml"]
        docker["Dockerfile"]
        reqs["requirements.txt"]
    end

    %% Flows
    theory -->|drives| calc
    calc -->|parameters| sims1
    calc -->|parameters| sims2
    sims1 -->|raw data| data
    sims2 -->|raw data| data
    sims1 -->|protocol outputs| experiments
    data -->|feeds| figs
    experiments -->|feeds| figs
    data -->|feeds| apps
    sims1 -->|simulation| apps
    figs -->|visuals| apps
    figs -->|generates| docVis
    genVis -->|uses figs| docVis
    apps -->|demo results| docVis

    %% Validation flows
    theory --> validate
    calc --> validate
    sims1 --> validate
    sims2 --> validate
    data --> validate
    experiments --> validate
    figs --> validate
    genVis --> validate
    apps --> validate
    tests --> validate

    %% CI flows
    ci --> validate
    ci --> genVis
    ci --> docker

    %% Click Events
    click theory "https://github.com/tnsr-q/pqrg-theory/tree/main/theory/"
    click deriv "https://github.com/tnsr-q/pqrg-theory/blob/main/DERIVATIONS.md"
    click calc "https://github.com/tnsr-q/pqrg-theory/tree/main/calculations/"
    click sims1 "https://github.com/tnsr-q/pqrg-theory/tree/main/simulations/"
    click sims2 "https://github.com/tnsr-q/pqrg-theory/tree/main/Simulations/"
    click data "https://github.com/tnsr-q/pqrg-theory/tree/main/data/"
    click experiments "https://github.com/tnsr-q/pqrg-theory/tree/main/experiments/"
    click figs "https://github.com/tnsr-q/pqrg-theory/tree/main/figs/"
    click genVis "https://github.com/tnsr-q/pqrg-theory/blob/main/generate_visuals.py"
    click docVis "https://github.com/tnsr-q/pqrg-theory/blob/main/VISUALIZATIONS.md"
    click apps "https://github.com/tnsr-q/pqrg-theory/tree/main/applications/"
    click validate "https://github.com/tnsr-q/pqrg-theory/blob/main/validate_theory.py"
    click tests "https://github.com/tnsr-q/pqrg-theory/tree/main/tests/"
    click ci "https://github.com/tnsr-q/pqrg-theory/blob/main/.github/workflows/generate_visuals.yml"
    click docker "https://github.com/tnsr-q/pqrg-theory/tree/main/Dockerfile"
    click reqs "https://github.com/tnsr-q/pqrg-theory/blob/main/requirements.txt"

    %% Styles
    classDef theory fill:#cce5ff,stroke:#004085,color:#004085
    classDef simulation fill:#d4edda,stroke:#155724,color:#155724
    classDef data fill:#fff3cd,stroke:#856404,color:#856404
    classDef visualization fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef application fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef testing fill:#f8f9fa,stroke:#6c757d,color:#6c757d
    classDef infra fill:#fdfdfe,stroke:#000000,color:#000000

    class theory,deriv,calc theory
    class sims1,sims2 simulation
    class data,experiments data
    class figs,genVis,docVis visualization
    class apps application
    class validate,tests testing
    class ci,docker,reqs infra
```
