# kanghengliu/tabula architecture

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

- Interactive diagram: https://gitdiagram.com/kanghengliu/tabula
- Repository: https://github.com/kanghengliu/tabula

## Overview

##### Project type and purpose
- This is an open‑source Python library (“Tabula”) for applying traditional reinforcement‑learning (RL) algorithms to simple games. It provides:
- Environments (boat, grid world, geo search)
- Solvers (Dynamic Programming, Monte Carlo, Temporal‑Difference)
- Utility routines (metrics collection, plotting, asset management)
- Example scripts and unit tests

##### File structure
- Top‑level files:
- README.md, LICENSE, pyproject.toml, requirements.txt → project metadata, dependencies, packaging
- docs/ → HTML/Jupyter docs for homework or demonstrations
- examples/ → example_usage.py illustrating CLI usage
- unit_tests/ → test suites for each module
- Core package: tabula/
- assets/ → images, plots, or other static resources
- environments.py → defines the game environments
- solvers.py → implements the three RL solvers
- utils.py → metrics collection, plotting functions, helper routines

##### README for additional insights
- Describes features (envs, solvers, metrics visualizations)
- Shows CLI usage pattern (`python examples/example_usage.py --env … --algo …`)
- Mentions outputs (convergence_plot.png, gameplay.gif, policy_visualization.png)
- Indicates how to build, install, and run tests

##### Detail without over‑splitting
- External files (pyproject.toml, requirements.txt) as part of the Packaging/Build component
- A separate Testing component that points at each core module

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    CLI["CLI / Example Runner"]:::entry
    click CLI "https://github.com/kanghengliu/tabula/blob/main/examples/example_usage.py"

    %% Core Logic
    subgraph "Core Logic"
        ENV["Environment Module"]:::core
        SOLVER["Solver Module"]:::core
    end
    click ENV "https://github.com/kanghengliu/tabula/blob/main/tabula/environments.py"
    click SOLVER "https://github.com/kanghengliu/tabula/blob/main/tabula/solvers.py"

    %% Utilities & Assets
    subgraph "Utilities & Assets"
        UTILS["Utilities Module"]:::util
        ASSETS["Asset Module"]:::util
    end
    click UTILS "https://github.com/kanghengliu/tabula/blob/main/tabula/utils.py"
    click ASSETS "https://github.com/kanghengliu/tabula/tree/main/tabula/assets/"

    %% Outputs
    OUTPUT["Output/Visualization (plots, gifs)"]:::output

    %% Packaging & Build
    subgraph "Packaging & Build"
        PJ["pyproject.toml"]:::build
        REQ["requirements.txt"]:::build
    end
    click PJ "https://github.com/kanghengliu/tabula/blob/main/pyproject.toml"
    click REQ "https://github.com/kanghengliu/tabula/blob/main/requirements.txt"

    %% Documentation
    DOCS["Documentation / Demonstrations"]:::docs
    click DOCS "https://github.com/kanghengliu/tabula/tree/main/docs/"

    %% Unit Testing
    subgraph "Unit Testing Suite"
        T_ENV["test_environments.py"]:::test
        T_SOLVER["test_solvers.py"]:::test
        T_UTILS["test_utils.py"]:::test
    end
    click T_ENV "https://github.com/kanghengliu/tabula/blob/main/unit_tests/test_environments.py"
    click T_SOLVER "https://github.com/kanghengliu/tabula/blob/main/unit_tests/test_solvers.py"
    click T_UTILS "https://github.com/kanghengliu/tabula/blob/main/unit_tests/test_utils.py"

    %% Relationships
    CLI -->|"initializes"| ENV
    CLI -->|"initializes"| SOLVER

    SOLVER -->|"queries state"| ENV
    ENV -->|"returns next state & reward"| SOLVER
    SOLVER -->|"records metrics"| UTILS
    UTILS -->|"writes visuals"| OUTPUT
    ASSETS -->|"provides templates"| UTILS
    ASSETS -->|"provides templates"| OUTPUT

    %% Testing Dependencies
    T_ENV -->|validates| ENV
    T_SOLVER -->|validates| SOLVER
    T_UTILS -->|validates| UTILS

    %% Other Dependencies
    CLI -->|"packaged by"| PJ
    CLI -->|"requires"| REQ
    CLI -->|"examples in"| DOCS

    %% Styling
    classDef entry fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef util fill:#bfb,stroke:#333,stroke-width:1px
    classDef output fill:#fbf,stroke:#333,stroke-width:1px
    classDef build fill:#ffd,stroke:#333,stroke-width:1px
    classDef docs fill:#bff,stroke:#333,stroke-width:1px
    classDef test fill:#fbb,stroke:#333,stroke-width:1px
```
