# jetnew/smawm architecture

> Architecture diagram of the GitHub repository jetnew/smawm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jetnew/smawm
- Repository: https://github.com/jetnew/smawm

## Overview

##### Main Components

a) Data Pipeline
- Dataset Generator
- Data Storage (datasets/expert, random, spurious)

b) Model Components
- World Model (WM)
- Structured Multi-Agent World Model (SMAWM)
- Reinforcement Learning Agents

c) Training Pipeline
- World Model Trainer
- SMAWM Trainer
- RL Agent Trainer

d) Experimentation & Analysis
- Experiment Runner
- Analysis Tools
- Visualization Components

##### Flow Directions

- Dataset Generator → Datasets → Training Components → Models → Experiments → Analysis

##### Detailed Subcomponents
For each major component, include relevant submodules:

World Model:
- VAE (vae.tar)
- MDRNN (mdrnn.tar)
- PPO Agent (wm-ppo.zip)

SMAWM:
- Structured Components (swm.tar)
- PPO Agent (swm-ppo.zip)

##### Specific elements
- Dataset types (expert, random, spurious)
- Model storage locations
- Analysis outputs (figures directory)
- Experiment results storage

##### Implementation Details
Files and their roles:
- generate_dataset.py
- train_wm.py
- train_swm.py
- train_rl.py
- run_experiments.py
- run_analysis.py

##### Storage Components
Storage locations:
- datasets/
- models/
- experiments/
- figures/

##### Metrics Flow
How performance metrics flow:
- Training metrics
- Experimental results
- Analysis outputs
- Visualization generation

- The parallel nature of WM and SMAWM implementations
- Data flow from generation to analysis
- Clear separation of training and evaluation phases
- Integration points between components
- Storage and retrieval patterns

Remember to include version information and any relevant hyperparameters that affect the system's behavior.

- How data flows through the system
- Where models are trained and stored
- How experiments are conducted
- How results are analyzed and visualized
- The relationship between traditional World Models and SMAWM

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Data_Pipeline
        DG[Dataset Generator]:::data
        DS[Data Storage]:::data
        DG --> DS
    end

    subgraph Model_Components
        subgraph WM[World Model]
            VAE[VAE]:::model
            MDRNN[MDRNN]:::model
            WM_PPO[WM PPO Agent]:::model
            VAE --> MDRNN
            MDRNN --> WM_PPO
        end
        
        subgraph SMAWM[Structured Multi-Agent WM]
            SWM[Structured Components]:::model
            SMAWM_PPO[SMAWM PPO Agent]:::model
            SWM --> SMAWM_PPO
        end
    end

    subgraph Training_Pipeline
        WMT[World Model Trainer]:::training
        SWMT[SMAWM Trainer]:::training
        RLT[RL Agent Trainer]:::training
    end

    subgraph Analysis_Components
        ER[Experiment Runner]:::analysis
        AT[Analysis Tools]:::analysis
        VC[Visualization Components]:::analysis
        RS[Results Storage]:::analysis
        
        ER --> AT
        AT --> VC
        AT --> RS
    end

    DS --> WMT
    DS --> SWMT
    WMT --> VAE
    WMT --> MDRNN
    SWMT --> SWM
    RLT --> WM_PPO
    RLT --> SMAWM_PPO
    
    WM --> ER
    SMAWM --> ER

    %% Component Mappings
    click DG "https://github.com/jetnew/smawm/blob/main/generate_dataset.py"
    click DS "https://github.com/jetnew/smawm/tree/main/datasets/"
    click VAE "https://github.com/jetnew/smawm/blob/main/models/*/vae.tar"
    click MDRNN "https://github.com/jetnew/smawm/blob/main/models/*/mdrnn.tar"
    click SWM "https://github.com/jetnew/smawm/blob/main/models/*/swm.tar"
    click WM_PPO "https://github.com/jetnew/smawm/blob/main/models/*/wm-ppo.zip"
    click SMAWM_PPO "https://github.com/jetnew/smawm/blob/main/models/*/swm-ppo.zip"
    click WMT "https://github.com/jetnew/smawm/blob/main/train_wm.py"
    click SWMT "https://github.com/jetnew/smawm/blob/main/train_swm.py"
    click RLT "https://github.com/jetnew/smawm/blob/main/train_rl.py"
    click ER "https://github.com/jetnew/smawm/blob/main/run_experiments.py"
    click AT "https://github.com/jetnew/smawm/blob/main/run_analysis.py"
    click VC "https://github.com/jetnew/smawm/blob/main/experiments/visualisation.ipynb"
    click RS "https://github.com/jetnew/smawm/blob/main/experiments/*.csv"

    classDef data fill:#3498db,stroke:#2980b9,color:white
    classDef model fill:#2ecc71,stroke:#27ae60,color:white
    classDef training fill:#e67e22,stroke:#d35400,color:white
    classDef analysis fill:#9b59b6,stroke:#8e44ad,color:white

    %% Legend
    subgraph Legend
        L1[Data Components]:::data
        L2[Model Components]:::model
        L3[Training Components]:::training
        L4[Analysis Components]:::analysis
    end
```
