# wiegerw/nerva-torch architecture

> Architecture diagram of the GitHub repository wiegerw/nerva-torch, 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/wiegerw/nerva-torch
- Repository: https://github.com/wiegerw/nerva-torch

## Overview

nerva-torch is a PyTorch-backed, manually differentiated MLP library. Its main workflow is to load minibatches, run feedforward and loss-gradient calculations, backpropagate through layers, and update parameters using a scheduled learning rate; training can also report evaluation statistics. The graph includes configurable layers, activations, losses, optimizers, initialization, matrix primitives, and the experiment CLI. Edges reflect README statements or shown source references; unsampled implementation details are not inferred.

Main entry points: [`src/nerva_torch/training.py`](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/training.py) (Training loop), [`src/nerva_torch/layers.py`](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/layers.py) (Network layers), [`src/nerva_torch/loss_functions.py`](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/loss_functions.py) (Loss functions), [`src/nerva_torch/datasets.py`](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/datasets.py) (Batch loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training workflow"]
  node_cli["MLP CLI<br/>[mlp.py]"]
  node_trainer["Training loop<br/>[training.py]"]
  node_scheduler["Learning rates<br/>[learning_rate.py]"]
  node_results["Training metrics<br/>[training.py]"]
end

subgraph group_model["MLP model"]
  node_model["MLP"]
  node_layers["Network layers<br/>[layers.py]"]
  node_optimizer["Optimizers<br/>[optimizers.py]"]
  node_initializer["Weight initialization"]
end

subgraph group_math["Math components"]
  node_activation["Activations"]
  node_softmax["Softmax functions"]
  node_loss["Loss functions<br/>[loss_functions.py]"]
  node_matrix["Matrix primitives"]
  node_torchloss["Torch loss helpers"]
end

subgraph group_support["Data and utilities"]
  node_dataset["Batch loader<br/>[datasets.py]"]
  node_npz["NPZ dataset"]
  node_utilities["I/O and utilities<br/>[utilities.py]"]
end

node_user(("Experimenter"))

node_user -.->|"configures"| node_cli
node_cli -->|"starts training"| node_trainer
node_trainer -->|"iterates batches"| node_dataset
node_dataset -->|"loads batches"| node_npz
node_trainer -->|"gets learning rate"| node_scheduler
node_trainer -->|"computes loss gradient"| node_loss
node_trainer -->|"runs and updates"| node_model
node_trainer -->|"computes statistics"| node_results
node_model -->|"dispatches forward and backward"| node_layers
node_layers -->|"applies activation"| node_activation
node_layers -->|"computes softmax"| node_softmax
node_layers -->|"updates parameters"| node_optimizer
node_layers -->|"sets weights"| node_initializer
node_layers -->|"uses primitives"| node_matrix
node_loss -->|"uses log-softmax"| node_softmax
node_loss -->|"uses activation functions"| node_activation
node_loss -->|"uses primitives"| node_matrix
node_softmax -->|"uses primitives"| node_matrix
node_dataset -->|"loads NPZ data"| node_utilities
node_model -->|"loads and saves weights"| node_utilities
node_trainer -->|"formats diagnostics"| node_utilities
node_torchloss -->|"uses data helpers"| node_dataset

click node_cli "https://github.com/wiegerw/nerva-torch/blob/main/tools/mlp.py"
click node_trainer "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/training.py"
click node_scheduler "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/learning_rate.py"
click node_dataset "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/datasets.py"
click node_model "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/multilayer_perceptron.py"
click node_layers "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/layers.py"
click node_activation "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/activation_functions.py"
click node_softmax "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/softmax_functions.py"
click node_loss "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/loss_functions.py"
click node_optimizer "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/optimizers.py"
click node_initializer "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/weight_initializers.py"
click node_matrix "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/matrix_operations.py"
click node_utilities "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/utilities.py"
click node_torchloss "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/loss_functions_torch.py"
click node_results "https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/training.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_cli,node_trainer,node_scheduler,node_results toneBlue
class node_model,node_layers,node_optimizer,node_initializer toneAmber
class node_activation,node_softmax,node_loss,node_matrix,node_torchloss toneMint
class node_dataset,node_npz,node_utilities toneRose
class node_user toneIndigo
```

## Components

### Training workflow

- [MLP CLI](https://github.com/wiegerw/nerva-torch/blob/main/tools/mlp.py): `tools/mlp.py`
- [Training loop](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/training.py): `src/nerva_torch/training.py`
- [Learning rates](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/learning_rate.py): `src/nerva_torch/learning_rate.py`
- [Training metrics](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/training.py): `src/nerva_torch/training.py`

### MLP model

- [MLP](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/multilayer_perceptron.py): `src/nerva_torch/multilayer_perceptron.py`
- [Network layers](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/layers.py): `src/nerva_torch/layers.py`
- [Optimizers](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/optimizers.py): `src/nerva_torch/optimizers.py`
- [Weight initialization](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/weight_initializers.py): `src/nerva_torch/weight_initializers.py`

### Math components

- [Activations](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/activation_functions.py): `src/nerva_torch/activation_functions.py`
- [Softmax functions](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/softmax_functions.py): `src/nerva_torch/softmax_functions.py`
- [Loss functions](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/loss_functions.py): `src/nerva_torch/loss_functions.py`
- [Matrix primitives](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/matrix_operations.py): `src/nerva_torch/matrix_operations.py`
- [Torch loss helpers](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/loss_functions_torch.py): `src/nerva_torch/loss_functions_torch.py`

### Data and utilities

- [Batch loader](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/datasets.py): `src/nerva_torch/datasets.py`
- **NPZ dataset**
- [I/O and utilities](https://github.com/wiegerw/nerva-torch/blob/main/src/nerva_torch/utilities.py): `src/nerva_torch/utilities.py`

### Other components

- **Experimenter**

## Connections

- Experimenter → MLP CLI: configures
- MLP CLI → Training loop: starts training (evidence: `tools/mlp.py`)
- Training loop → Batch loader: iterates batches (evidence: `src/nerva_torch/training.py`)
- Batch loader → NPZ dataset: loads batches (evidence: `src/nerva_torch/datasets.py`)
- Training loop → Learning rates: gets learning rate (evidence: `src/nerva_torch/training.py`)
- Training loop → Loss functions: computes loss gradient (evidence: `src/nerva_torch/training.py`)
- Training loop → MLP: runs and updates (evidence: `README.md`)
- Training loop → Training metrics: computes statistics (evidence: `src/nerva_torch/training.py`)
- MLP → Network layers: dispatches forward and backward (evidence: `src/nerva_torch/multilayer_perceptron.py`)
- Network layers → Activations: applies activation (evidence: `src/nerva_torch/layers.py`)
- Network layers → Softmax functions: computes softmax (evidence: `src/nerva_torch/layers.py`)
- Network layers → Optimizers: updates parameters (evidence: `src/nerva_torch/layers.py`)
- Network layers → Weight initialization: sets weights (evidence: `src/nerva_torch/layers.py`)
- Network layers → Matrix primitives: uses primitives (evidence: `src/nerva_torch/layers.py`)
- Loss functions → Softmax functions: uses log-softmax (evidence: `src/nerva_torch/loss_functions.py`)
- Loss functions → Activations: uses activation functions (evidence: `src/nerva_torch/loss_functions.py`)
- Loss functions → Matrix primitives: uses primitives (evidence: `src/nerva_torch/loss_functions.py`)
- Softmax functions → Matrix primitives: uses primitives (evidence: `src/nerva_torch/softmax_functions.py`)
- Batch loader → I/O and utilities: loads NPZ data (evidence: `src/nerva_torch/datasets.py`)
- MLP → I/O and utilities: loads and saves weights (evidence: `src/nerva_torch/multilayer_perceptron.py`)
- Training loop → I/O and utilities: formats diagnostics (evidence: `src/nerva_torch/training.py`)
- Torch loss helpers → Batch loader: uses data helpers (evidence: `src/nerva_torch/loss_functions_torch.py`)
