# flavio-ponzina/microhd architecture

> Architecture diagram of the GitHub repository flavio-ponzina/microhd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flavio-ponzina/microhd
- Repository: https://github.com/flavio-ponzina/microhd
- Video tour (about a minute): https://gitdiagram.com/flavio-ponzina/microhd/video

## Overview

This repository provides two command-line experiments for training and resource-aware optimization of hyperdimensional classifiers: one uses ID-level encoding and the other projection encoding. Each selects and prepares a dataset, trains and evaluates a baseline, then searches encoding dimensions and quantization settings (plus levels for ID-level) under accuracy-drop thresholds, reporting estimated memory and bit operations. Shared encoders, classifier, training/evaluation routines, and requirement calculations live in utils.py. Edges follow explicit calls in the excerpts; external dataset sources are shown as inputs, not as inspected integrations.

Main entry points: [`code/MicroHD-idlev-binary-search.py`](https://github.com/flavio-ponzina/microhd/blob/main/code/MicroHD-idlev-binary-search.py) (ID-level search), [`code/MicroHD-proj-binary-search.py`](https://github.com/flavio-ponzina/microhd/blob/main/code/MicroHD-proj-binary-search.py) (Projection search), [`code/utils.py`](https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py) (Train and evaluate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiments["Optimization experiments"]
  node_idlev["ID-level search"]
  node_proj["Projection search"]
end

subgraph group_runtime["Model runtime"]
  node_encoders["HD encoders<br/>[utils.py]"]
  node_classifier["HD classifier<br/>[utils.py]"]
  node_training["Train and evaluate<br/>[utils.py]"]
  node_requirements["Resource estimates<br/>[utils.py]"]
end

node_user(("Experiment user"))
node_datasets[("Dataset sources")]

node_user -->|"runs"| node_idlev
node_user -->|"runs"| node_proj
node_idlev -->|"loads data"| node_datasets
node_proj -->|"loads data"| node_datasets
node_idlev -->|"creates encoder"| node_encoders
node_proj -->|"creates encoder"| node_encoders
node_idlev -->|"creates model"| node_classifier
node_proj -->|"creates model"| node_classifier
node_idlev -->|"trains and evaluates"| node_training
node_proj -->|"trains and evaluates"| node_training
node_idlev -->|"estimates costs"| node_requirements
node_proj -->|"estimates costs"| node_requirements
node_training -->|"encodes batches"| node_encoders
node_training -->|"updates and scores"| node_classifier

click node_idlev "https://github.com/flavio-ponzina/microhd/blob/main/code/MicroHD-idlev-binary-search.py"
click node_proj "https://github.com/flavio-ponzina/microhd/blob/main/code/MicroHD-proj-binary-search.py"
click node_encoders "https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py"
click node_classifier "https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py"
click node_training "https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py"
click node_requirements "https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_idlev,node_proj,node_user toneBlue
class node_encoders,node_classifier,node_training,node_requirements,node_datasets toneAmber
```

## Components

### Optimization experiments

- [ID-level search](https://github.com/flavio-ponzina/microhd/blob/main/code/MicroHD-idlev-binary-search.py): `code/MicroHD-idlev-binary-search.py`
- [Projection search](https://github.com/flavio-ponzina/microhd/blob/main/code/MicroHD-proj-binary-search.py): `code/MicroHD-proj-binary-search.py`

### Model runtime

- [HD encoders](https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py): `code/utils.py`
- [HD classifier](https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py): `code/utils.py`
- [Train and evaluate](https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py): `code/utils.py`
- [Resource estimates](https://github.com/flavio-ponzina/microhd/blob/main/code/utils.py): `code/utils.py`

### Other components

- **Experiment user**
- **Dataset sources**

## Connections

- Experiment user → ID-level search: runs (evidence: `code/MicroHD-idlev-binary-search.py`)
- Experiment user → Projection search: runs (evidence: `code/MicroHD-proj-binary-search.py`)
- ID-level search → Dataset sources: loads data (evidence: `code/MicroHD-idlev-binary-search.py`)
- Projection search → Dataset sources: loads data (evidence: `code/MicroHD-proj-binary-search.py`)
- ID-level search → HD encoders: creates encoder (evidence: `code/MicroHD-idlev-binary-search.py`)
- Projection search → HD encoders: creates encoder (evidence: `code/MicroHD-proj-binary-search.py`)
- ID-level search → HD classifier: creates model (evidence: `code/MicroHD-idlev-binary-search.py`)
- Projection search → HD classifier: creates model (evidence: `code/MicroHD-proj-binary-search.py`)
- ID-level search → Train and evaluate: trains and evaluates (evidence: `code/MicroHD-idlev-binary-search.py`)
- Projection search → Train and evaluate: trains and evaluates (evidence: `code/MicroHD-proj-binary-search.py`)
- ID-level search → Resource estimates: estimates costs (evidence: `code/MicroHD-idlev-binary-search.py`)
- Projection search → Resource estimates: estimates costs (evidence: `code/MicroHD-proj-binary-search.py`)
- Train and evaluate → HD encoders: encodes batches (evidence: `code/utils.py`)
- Train and evaluate → HD classifier: updates and scores (evidence: `code/utils.py`)