# nuistmrchest/libmatchstick architecture

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

- Interactive diagram: https://gitdiagram.com/nuistmrchest/libmatchstick
- Repository: https://github.com/nuistmrchest/libmatchstick
- Video tour (about a minute): https://gitdiagram.com/nuistmrchest/libmatchstick/video

## Overview

LibMatchstick is a lightweight C++/CUDA neural-network library with native C++ and opaque-handle C APIs. Its main workflow configures an MLP or CNN, supplies matrix/tensor input and targets, trains or runs inference, and can save or load parameters. The README documents the MLP/CNN composition and API capabilities; sampled headers establish the data types and network interfaces, but do not show the CUDA implementation call paths.

Main entry points: [`include/matchstick/network.h`](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/network.h) (CNN), [`include/matchstick_c/network.h`](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick_c/network.h) (Opaque C API), [`src/c_api/matrix_capi.cu`](https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/matrix_capi.cu) (C matrix handles), [`src/c_api/tensor_3d_capi.cu`](https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/tensor_3d_capi.cu) (C 3D tensor handles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_networks["Neural networks"]
  node_mlp["MLP<br/>[network.h]"]
  node_cnn["CNN<br/>[network.h]"]
  node_cpp_api["C++ API<br/>[network.h]"]
end

subgraph group_compute["Compute components"]
  node_layer["Network layers<br/>[layer.h]"]
  node_activation["Activations<br/>[activation.h]"]
  node_loss["Loss functions<br/>[loss.h]"]
end

subgraph group_data["Data containers"]
  node_matrix["Matrix operations<br/>[matrix.cu]"]
  node_tensor3["3D tensor operations<br/>[tensor_3d.cu]"]
  node_tensor4["4D tensor operations<br/>[tensor_4d.cu]"]
end

subgraph group_capi["C API"]
  node_c_api["Opaque C API<br/>[network.h]"]
  node_c_matrix["C matrix handles<br/>[matrix_capi.cu]"]
  node_c_tensor3["C 3D tensor handles<br/>[tensor_3d_capi.cu]"]
  node_c_tensor4["C 4D tensor handles<br/>[tensor_4d_capi.cu]"]
  node_c_network["C network handles<br/>[network_capi.cu]"]
end

node_developer(("Application developer"))

node_developer -->|"configures and calls"| node_cpp_api
node_cpp_api -->|"configures and trains"| node_mlp
node_cpp_api -->|"configures and trains"| node_cnn
node_mlp -->|"sets activations"| node_activation
node_mlp -->|"sets loss"| node_loss
node_cnn -->|"configures convolution and pooling"| node_layer
node_cnn -->|"uses MLP head"| node_mlp
node_cnn -->|"accepts input"| node_tensor3
node_cnn -->|"saves kernels"| node_tensor4
node_mlp -->|"accepts input and parameters"| node_matrix
node_developer -->|"calls opaque handles"| node_c_api
node_c_api -->|"wraps network operations"| node_c_network
node_c_api -->|"exposes matrix handles"| node_c_matrix
node_c_api -->|"exposes tensor handles"| node_c_tensor3
node_c_api -->|"exposes tensor handles"| node_c_tensor4
node_c_network -->|"wraps C++ networks"| node_cpp_api
node_c_matrix -->|"wraps matrix type"| node_matrix
node_c_tensor3 -->|"wraps tensor type"| node_tensor3
node_c_tensor4 -->|"wraps tensor type"| node_tensor4

click node_mlp "https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/network.h"
click node_cnn "https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/network.h"
click node_layer "https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/layer.h"
click node_activation "https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/activation.h"
click node_loss "https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/loss.h"
click node_matrix "https://github.com/nuistmrchest/libmatchstick/blob/master/src/cpp/matrix.cu"
click node_tensor3 "https://github.com/nuistmrchest/libmatchstick/blob/master/src/cpp/tensor_3d.cu"
click node_tensor4 "https://github.com/nuistmrchest/libmatchstick/blob/master/src/cpp/tensor_4d.cu"
click node_cpp_api "https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/network.h"
click node_c_api "https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick_c/network.h"
click node_c_matrix "https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/matrix_capi.cu"
click node_c_tensor3 "https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/tensor_3d_capi.cu"
click node_c_tensor4 "https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/tensor_4d_capi.cu"
click node_c_network "https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/network_capi.cu"

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_mlp,node_cnn,node_cpp_api toneBlue
class node_layer,node_activation,node_loss toneAmber
class node_matrix,node_tensor3,node_tensor4 toneMint
class node_c_api,node_c_matrix,node_c_tensor3,node_c_tensor4,node_c_network toneRose
class node_developer toneIndigo
```

## Components

### Neural networks

- [MLP](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/network.h): `include/matchstick/network.h`
- [CNN](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/network.h): `include/matchstick/network.h`
- [C++ API](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/network.h): `include/matchstick/network.h`

### Compute components

- [Network layers](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/layer.h): `include/matchstick/layer.h`
- [Activations](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/activation.h): `include/matchstick/activation.h`
- [Loss functions](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick/loss.h): `include/matchstick/loss.h`

### Data containers

- [Matrix operations](https://github.com/nuistmrchest/libmatchstick/blob/master/src/cpp/matrix.cu): `src/cpp/matrix.cu`
- [3D tensor operations](https://github.com/nuistmrchest/libmatchstick/blob/master/src/cpp/tensor_3d.cu): `src/cpp/tensor_3d.cu`
- [4D tensor operations](https://github.com/nuistmrchest/libmatchstick/blob/master/src/cpp/tensor_4d.cu): `src/cpp/tensor_4d.cu`

### C API

- [Opaque C API](https://github.com/nuistmrchest/libmatchstick/blob/master/include/matchstick_c/network.h): `include/matchstick_c/network.h`
- [C matrix handles](https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/matrix_capi.cu): `src/c_api/matrix_capi.cu`
- [C 3D tensor handles](https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/tensor_3d_capi.cu): `src/c_api/tensor_3d_capi.cu`
- [C 4D tensor handles](https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/tensor_4d_capi.cu): `src/c_api/tensor_4d_capi.cu`
- [C network handles](https://github.com/nuistmrchest/libmatchstick/blob/master/src/c_api/network_capi.cu): `src/c_api/network_capi.cu`

### Other components

- **Application developer**

## Connections

- Application developer → C++ API: configures and calls (evidence: `README.md`)
- C++ API → MLP: configures and trains (evidence: `README.md`)
- C++ API → CNN: configures and trains (evidence: `README.md`)
- MLP → Activations: sets activations (evidence: `README.md`)
- MLP → Loss functions: sets loss (evidence: `README.md`)
- CNN → Network layers: configures convolution and pooling (evidence: `README.md`)
- CNN → MLP: uses MLP head (evidence: `README.md`)
- CNN → 3D tensor operations: accepts input (evidence: `include/matchstick/network.h`)
- CNN → 4D tensor operations: saves kernels (evidence: `include/matchstick/network.h`)
- MLP → Matrix operations: accepts input and parameters (evidence: `include/matchstick/network.h`)
- Application developer → Opaque C API: calls opaque handles (evidence: `README.md`)
- Opaque C API → C network handles: wraps network operations (evidence: `README.md`)
- Opaque C API → C matrix handles: exposes matrix handles (evidence: `README.md`)
- Opaque C API → C 3D tensor handles: exposes tensor handles (evidence: `README.md`)
- Opaque C API → C 4D tensor handles: exposes tensor handles (evidence: `README.md`)
- C network handles → C++ API: wraps C++ networks
- C matrix handles → Matrix operations: wraps matrix type
- C 3D tensor handles → 3D tensor operations: wraps tensor type
- C 4D tensor handles → 4D tensor operations: wraps tensor type
