# qkchambers/trabalho1-cps841 architecture

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

- Interactive diagram: https://gitdiagram.com/qkchambers/trabalho1-cps841
- Repository: https://github.com/qkchambers/trabalho1-cps841

## Overview

##### Project type and purpose
- This is an academic/research monorepo containing two related model implementations (BTHOWeN and ULEEN) of the Bloom WiSARD neural‐like classifier.
- Each implementation has two halves:
a. A hardware description (RTL) generator and testbench for SystemVerilog (via Mako templates).
b. A software reference model in Python for loading data, training, and evaluation.
- The goal is to reproduce and extend Bloom WiSARD results on multiple UCI datasets using both hardware‐mappable RTL and a software model.

##### File structure
- Top level: Docker/DevContainer configs, `.env`, `README.md`, and two sibling directories `BTHOWeN/` and `ULEEN/`.
- Each of `BTHOWeN/` and `ULEEN/` contains:
- `rtl/` – Mako templates (`mako_srcs`) + build scripts (`rtl/build`) + generated RTL + synthesis reports + testbench code.
- `software_model/` – Python modules for data conversion, model definition, training, evaluation, and utility scripts.
- `requirements.txt`, `README.md`, and `Makefile` or `setup.py` for packaging.
- There's also a top‐level `models/` directory (to store persisted model files) and global `requirements.txt` for Docker builds.

##### README for additional insights
- The README clarifies launch configurations (`train_swept_models.py`, `evaluate.py`, `full_run.py`) and the datasets used.
- It points out how `example.json` configures ULEEN parameters.
- It references academic papers and GitHub repos for the underlying algorithms.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        DevContainer["DevContainer Config"]:::tool
        DockerfileNode["Dockerfile"]:::tool
    end
    click DevContainer "https://github.com/qkchambers/trabalho1-cps841/blob/main/.devcontainer/devcontainer.json"
    click DockerfileNode "https://github.com/qkchambers/trabalho1-cps841/tree/main/Dockerfile"

    %% Dataset Store
    subgraph "Dataset Store"
        Dataset["UCI Datasets (models/)"]:::data
    end
    click Dataset "https://github.com/qkchambers/trabalho1-cps841/tree/main/models/"

    %% BTHOWeN Subsystem
    subgraph "BTHOWeN Subsystem"
        subgraph "RTL Generation"
            B_MakeRTL["make_rtl.py"]:::hardware
            B_Render["render_template.py"]:::hardware
            B_Mako["mako_srcs/"]:::hardware
        end
        subgraph "Generated Verilog"
            B_Verilog["rtl/build/"]:::hardware
        end
        subgraph "Testbench & Simulation"
            B_tb1["test_discriminator.sv"]:::hardware
            B_tb2["test_filter.sv"]:::hardware
            B_tb3["test_hash_unit.sv"]:::hardware
            B_tb4["test_interface_basic.sv"]:::hardware
            B_tb5["test_mnist.sv"]:::hardware
            B_tb6["test_wisard_top.sv"]:::hardware
        end
        subgraph "Synthesis & Reports"
            B_Power["power/"]:::report
            B_Util["utilization/"]:::report
        end
        subgraph "Software Model"
            B_convert["convert_dset.py"]:::software
            B_bloom["bloom_filter.py"]:::software
            B_wisard["wisard.py"]:::software
            B_train["train_swept_models.py"]:::software
            B_eval["evaluate.py"]:::software
            B_size["calc_model_size.py"]:::software
            B_tabular["tabular_tools.py"]:::software
        end
    end

    click B_MakeRTL "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/rtl/build/make_rtl.py"
    click B_Render "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/rtl/build/render_template.py"
    click B_Mako "https://github.com/qkchambers/trabalho1-cps841/tree/main/BTHOWeN/rtl/mako_srcs/"
    click B_Verilog "https://github.com/qkchambers/trabalho1-cps841/tree/main/BTHOWeN/rtl/build/"
    click B_tb1 "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/rtl/testbench/test_discriminator.sv"
    click B_tb2 "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/rtl/testbench/test_filter.sv"
    click B_tb3 "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/rtl/testbench/test_hash_unit.sv"
    click B_tb4 "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/rtl/testbench/test_interface_basic.sv"
    click B_tb5 "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/rtl/testbench/test_mnist.sv"
    click B_tb6 "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/rtl/testbench/test_wisard_top.sv"
    click B_Power "https://github.com/qkchambers/trabalho1-cps841/tree/main/BTHOWeN/rtl/synthesis_reports/power/"
    click B_Util "https://github.com/qkchambers/trabalho1-cps841/tree/main/BTHOWeN/rtl/synthesis_reports/utilization/"
    click B_convert "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/software_model/convert_dset.py"
    click B_bloom "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/software_model/bloom_filter.py"
    click B_wisard "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/software_model/wisard.py"
    click B_train "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/software_model/train_swept_models.py"
    click B_eval "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/software_model/evaluate.py"
    click B_size "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/software_model/calc_model_size.py"
    click B_tabular "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/software_model/tabular_tools.py"

    %% ULEEN Subsystem
    subgraph "ULEEN Subsystem"
        subgraph "RTL Generation"
            U_MakeRTL["make_rtl.py"]:::hardware
            U_Render["render_template.py"]:::hardware
            U_Mako["mako_srcs/"]:::hardware
        end
        subgraph "Testbench & Simulation"
            U_tb["test_functional_correctness.sv"]:::hardware
        end
        subgraph "Software Model"
            U_get["get_datasets.py"]:::software
            U_train["train_model.py"]:::software
            U_prune["prune_model.py"]:::software
            U_finalize["finalize_model.py"]:::software
            U_full["full_run.py"]:::software
            U_model["model.py"]:::software
            U_example["example.json"]:::software
            U_cpp1["cpp/h3_hash.cpp"]:::software
            U_cpp2["cpp/h3_hash.h"]:::software
        end
    end

    click U_MakeRTL "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/rtl/build/make_rtl.py"
    click U_Render "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/rtl/build/render_template.py"
    click U_Mako "https://github.com/qkchambers/trabalho1-cps841/tree/main/ULEEN/rtl/mako_srcs/"
    click U_tb "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/rtl/testbench/test_functional_correctness.sv"
    click U_get "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/get_datasets.py"
    click U_train "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/train_model.py"
    click U_prune "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/prune_model.py"
    click U_finalize "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/finalize_model.py"
    click U_full "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/full_run.py"
    click U_model "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/model.py"
    click U_example "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/example.json"
    click U_cpp1 "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/cpp/h3_hash.cpp"
    click U_cpp2 "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/cpp/h3_hash.h"

    %% Orchestration & Results
    Orchestration["Orchestration Scripts"]:::tool
    Results["Results & Reports"]:::report

    click Orchestration "https://github.com/qkchambers/trabalho1-cps841/blob/main/BTHOWeN/software_model/train_swept_models.py"
    click Orchestration "https://github.com/qkchambers/trabalho1-cps841/blob/main/ULEEN/software_model/full_run.py"

    %% Relationships
    Dataset --> B_convert
    Dataset --> U_get
    B_MakeRTL --> B_Verilog
    B_Verilog --> B_tb1 & B_tb2 & B_tb3 & B_tb4 & B_tb5 & B_tb6
    B_tb1 & B_tb2 & B_tb3 & B_tb4 & B_tb5 & B_tb6 --> B_Power & B_Util
    U_MakeRTL --> B_Verilog
    U_VerilogNeed["Generated Verilog"]:::hardware
    click U_VerilogNeed "https://github.com/qkchambers/trabalho1-cps841/tree/main/ULEEN/rtl/build/"
    U_MakeRTL --> U_VerilogNeed
    U_VerilogNeed --> U_tb
    B_convert --> B_wisard
    B_wisard --> B_train
    B_train --> B_eval
    U_get --> U_model
    U_model --> U_train
    U_train --> U_prune --> U_finalize --> U_full
    B_train --> Orchestration
    U_full --> Orchestration
    Orchestration --> Results

    %% Styles
    classDef tool fill:#f0ad4e,stroke:#333,color:#000;
    classDef data fill:#d3d3d3,stroke:#333,color:#000;
    classDef hardware fill:#007bff,stroke:#333,color:#fff;
    classDef software fill:#28a745,stroke:#333,color:#fff;
    classDef report fill:#6f42c1,stroke:#333,color:#fff;
```
