# amineux/hysmap architecture

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

- Interactive diagram: https://gitdiagram.com/amineux/hysmap
- Repository: https://github.com/amineux/hysmap

## Overview

HySMap is a C++20 SNN-to-mesh mapper that models each neuron's axon as a multicast hyperedge and optimizes activity-weighted routing cost. Its principal workflow is to load or generate a network, represent it as a directed hypergraph, partition neurons and place logical cores on a mesh, refine the mapping against multicast cost, then report or export results. The README documents this workflow and the mapper variants; source-index import lists support some internal dependencies, but several implementation details were not excerpted.

Main entry points: [`src/mapper.cpp`](https://github.com/amineux/hysmap/blob/main/src/mapper.cpp) (Mapper orchestration), [`src/hypergraph.cpp`](https://github.com/amineux/hysmap/blob/main/src/hypergraph.cpp) (Directed hypergraph), [`src/cli.cpp`](https://github.com/amineux/hysmap/blob/main/src/cli.cpp) (CLI), [`python/bindings.cpp`](https://github.com/amineux/hysmap/blob/main/python/bindings.cpp) (Python bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_cli["CLI<br/>[cli.cpp]"]
  node_python["Python bindings<br/>[bindings.cpp]"]
end

subgraph group_model["Network Model"]
  node_network_io["Network JSON<br/>[io.cpp]"]
  node_generator["SNN generator<br/>[snn_generator.cpp]"]
  node_hypergraph["Directed hypergraph<br/>[hypergraph.cpp]"]
end

subgraph group_mapping["Mapping"]
  node_mesh["Mesh NoC<br/>[mesh.cpp]"]
  node_partition["Neuron partitioning<br/>[partition.cpp]"]
  node_placement["Core placement<br/>[placement.cpp]"]
  node_mapper["Mapper orchestration<br/>[mapper.cpp]"]
end

subgraph group_evaluation["Evaluation"]
  node_incremental["Incremental evaluator<br/>[incremental.cpp]"]
  node_cost["Multicast cost<br/>[cost.cpp]"]
  node_parallel["Parallel work<br/>[parallel.hpp]"]
  node_types["Mapping and metrics<br/>[types.hpp]"]
end

subgraph group_results["Results"]
  node_result_io["Metrics and results<br/>[io.cpp]"]
  node_export["Loihi-style export<br/>[export.cpp]"]
end

node_user(("User"))
node_output(("Mapping results"))

node_user -->|"runs commands"| node_cli
node_user -.->|"uses bindings"| node_python
node_network_io -->|"loads network"| node_hypergraph
node_generator -->|"generates network"| node_hypergraph
node_hypergraph -->|"maps network"| node_mapper
node_mesh -->|"provides topology"| node_mapper
node_mapper -->|"seeds and refines"| node_partition
node_mapper -->|"seeds and places"| node_placement
node_mapper -->|"refines by ΔJ"| node_incremental
node_mapper -->|"evaluates mapping"| node_cost
node_incremental -->|"updates cost"| node_cost
node_mapper -->|"parallelizes gains"| node_parallel
node_mapper -->|"returns mapping"| node_types
node_mapper -->|"reports metrics"| node_result_io
node_mapper -->|"exports mapping"| node_export
node_result_io -->|"writes results"| node_output
node_export -->|"writes export"| node_output
node_python -->|"runs mapper"| node_mapper
node_cli -->|"runs mapping"| node_mapper

click node_cli "https://github.com/amineux/hysmap/blob/main/src/cli.cpp"
click node_python "https://github.com/amineux/hysmap/blob/main/python/bindings.cpp"
click node_network_io "https://github.com/amineux/hysmap/blob/main/src/io.cpp"
click node_generator "https://github.com/amineux/hysmap/blob/main/src/snn_generator.cpp"
click node_hypergraph "https://github.com/amineux/hysmap/blob/main/src/hypergraph.cpp"
click node_mesh "https://github.com/amineux/hysmap/blob/main/src/mesh.cpp"
click node_partition "https://github.com/amineux/hysmap/blob/main/src/partition.cpp"
click node_placement "https://github.com/amineux/hysmap/blob/main/src/placement.cpp"
click node_mapper "https://github.com/amineux/hysmap/blob/main/src/mapper.cpp"
click node_incremental "https://github.com/amineux/hysmap/blob/main/src/incremental.cpp"
click node_cost "https://github.com/amineux/hysmap/blob/main/src/cost.cpp"
click node_parallel "https://github.com/amineux/hysmap/blob/main/include/hysmap/parallel.hpp"
click node_types "https://github.com/amineux/hysmap/blob/main/include/hysmap/types.hpp"
click node_result_io "https://github.com/amineux/hysmap/blob/main/src/io.cpp"
click node_export "https://github.com/amineux/hysmap/blob/main/src/export.cpp"

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_cli,node_python,node_user toneBlue
class node_network_io,node_generator,node_hypergraph toneAmber
class node_mesh,node_partition,node_placement,node_mapper toneMint
class node_incremental,node_cost,node_parallel,node_types toneRose
class node_result_io,node_export,node_output toneIndigo
```

## Components

### User Interface

- [CLI](https://github.com/amineux/hysmap/blob/main/src/cli.cpp): `src/cli.cpp`
- [Python bindings](https://github.com/amineux/hysmap/blob/main/python/bindings.cpp): `python/bindings.cpp`

### Network Model

- [Network JSON](https://github.com/amineux/hysmap/blob/main/src/io.cpp): `src/io.cpp`
- [SNN generator](https://github.com/amineux/hysmap/blob/main/src/snn_generator.cpp): `src/snn_generator.cpp`
- [Directed hypergraph](https://github.com/amineux/hysmap/blob/main/src/hypergraph.cpp): `src/hypergraph.cpp`

### Mapping

- [Mesh NoC](https://github.com/amineux/hysmap/blob/main/src/mesh.cpp): `src/mesh.cpp`
- [Neuron partitioning](https://github.com/amineux/hysmap/blob/main/src/partition.cpp): `src/partition.cpp`
- [Core placement](https://github.com/amineux/hysmap/blob/main/src/placement.cpp): `src/placement.cpp`
- [Mapper orchestration](https://github.com/amineux/hysmap/blob/main/src/mapper.cpp): `src/mapper.cpp`

### Evaluation

- [Incremental evaluator](https://github.com/amineux/hysmap/blob/main/src/incremental.cpp): `src/incremental.cpp`
- [Multicast cost](https://github.com/amineux/hysmap/blob/main/src/cost.cpp): `src/cost.cpp`
- [Parallel work](https://github.com/amineux/hysmap/blob/main/include/hysmap/parallel.hpp): `include/hysmap/parallel.hpp`
- [Mapping and metrics](https://github.com/amineux/hysmap/blob/main/include/hysmap/types.hpp): `include/hysmap/types.hpp`

### Results

- [Metrics and results](https://github.com/amineux/hysmap/blob/main/src/io.cpp): `src/io.cpp`
- [Loihi-style export](https://github.com/amineux/hysmap/blob/main/src/export.cpp): `src/export.cpp`

### Other components

- **User**
- **Mapping results**

## Connections

- User → CLI: runs commands (evidence: `README.md`)
- User → Python bindings: uses bindings (evidence: `README.md`)
- Network JSON → Directed hypergraph: loads network (evidence: `README.md`)
- SNN generator → Directed hypergraph: generates network (evidence: `README.md`)
- Directed hypergraph → Mapper orchestration: maps network (evidence: `README.md`)
- Mesh NoC → Mapper orchestration: provides topology (evidence: `README.md`)
- Mapper orchestration → Neuron partitioning: seeds and refines (evidence: `README.md`)
- Mapper orchestration → Core placement: seeds and places (evidence: `README.md`)
- Mapper orchestration → Incremental evaluator: refines by ΔJ (evidence: `README.md`)
- Mapper orchestration → Multicast cost: evaluates mapping (evidence: `README.md`)
- Incremental evaluator → Multicast cost: updates cost (evidence: `README.md`)
- Mapper orchestration → Parallel work: parallelizes gains (evidence: `README.md`)
- Mapper orchestration → Mapping and metrics: returns mapping
- Mapper orchestration → Metrics and results: reports metrics (evidence: `README.md`)
- Mapper orchestration → Loihi-style export: exports mapping (evidence: `README.md`)
- Metrics and results → Mapping results: writes results (evidence: `README.md`)
- Loihi-style export → Mapping results: writes export (evidence: `README.md`)
- Python bindings → Mapper orchestration: runs mapper (evidence: `README.md`)
- CLI → Mapper orchestration: runs mapping (evidence: `README.md`)
