# parm2006/neuralnetworksrust architecture

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

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

## Overview

NeuralNetworksRust is a pure-Rust deep-learning framework, with an MNIST example demonstrating training, evaluation, inference, and checkpointing. The training workflow loads image and label data, runs a modular model, computes loss and gradients, and updates parameters; evaluation and single-sample inference reuse the model and saved weights. The graph also captures the framework’s tensor/autograd, layer, loss, optimizer, and state-persistence capabilities. The README documents a Python visualizer, but its implementation was not sampled, so its internal wiring is omitted.

Main entry points: [`mnist.rs`](https://github.com/parm2006/neuralnetworksrust/blob/main/mnist.rs) (Train and inference), [`src/modules/sequential.rs`](https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/sequential.rs) (Sequential model), [`src/tensor/tensor.rs`](https://github.com/parm2006/neuralnetworksrust/blob/main/src/tensor/tensor.rs) (Tensor and autograd), [`src/losses/cross_entropy.rs`](https://github.com/parm2006/neuralnetworksrust/blob/main/src/losses/cross_entropy.rs) (Cross entropy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["MNIST workflows"]
  node_mnist["Train and inference<br/>[mnist.rs]"]
  node_test_eval["Evaluation<br/>[mnist.rs]"]
  node_single_inference["Single inference<br/>[mnist.rs]"]
  node_python_visualizer["Python visualizer<br/>[infer.py]"]
end

subgraph group_runtime["Tensor runtime"]
  node_tensor["Tensor and autograd<br/>[tensor.rs]"]
end

subgraph group_models["Model components"]
  node_module_trait["Module and state API<br/>[module.rs]"]
  node_sequential["Sequential model<br/>[sequential.rs]"]
  node_linear["Linear layer<br/>[linear.rs]"]
  node_flatten["Flatten layer<br/>[flatten.rs]"]
  node_activations["Activations"]
end

subgraph group_learning["Training components"]
  node_loss_api["Loss API<br/>[loss.rs]"]
  node_cross_entropy["Cross entropy<br/>[cross_entropy.rs]"]
  node_other_losses["MSE and NLL"]
  node_optimizer_api["Optimizer API<br/>[optimizer.rs]"]
  node_sgd["SGD<br/>[sgd.rs]"]
  node_adamw["AdamW<br/>[adamw.rs]"]
end

subgraph group_persistence["Model persistence"]
  node_checkpoint["Binary checkpoint"]
end

node_user(("User"))
node_dataset["MNIST files"]

node_user -->|"starts"| node_mnist
node_mnist -->|"reads training data"| node_dataset
node_mnist -->|"builds model"| node_sequential
node_mnist -->|"computes loss"| node_cross_entropy
node_mnist -->|"updates parameters"| node_adamw
node_mnist -->|"evaluates after training"| node_test_eval
node_test_eval -->|"reads test data"| node_dataset
node_test_eval -->|"runs forward pass"| node_sequential
node_test_eval -->|"computes test loss"| node_cross_entropy
node_mnist -->|"selects sample mode"| node_single_inference
node_single_inference -->|"reads test sample"| node_dataset
node_single_inference -->|"runs forward pass"| node_sequential
node_single_inference -->|"loads weights"| node_checkpoint
node_mnist -->|"saves weights"| node_checkpoint
node_mnist -->|"creates batches and backpropagates"| node_tensor
node_sequential -->|"implements module API"| node_module_trait
node_module_trait -->|"tracks parameters and state"| node_tensor
node_sequential -->|"contains layers"| node_linear
node_sequential -->|"contains layers"| node_flatten
node_sequential -->|"contains activations"| node_activations
node_cross_entropy -->|"implements"| node_loss_api
node_other_losses -->|"implements"| node_loss_api
node_cross_entropy -->|"builds differentiable loss"| node_tensor
node_adamw -->|"implements"| node_optimizer_api
node_sgd -->|"implements"| node_optimizer_api
node_adamw -->|"reads gradients and updates data"| node_tensor
node_sgd -->|"reads gradients and updates data"| node_tensor
node_user -.->|"launches optional viewer"| node_python_visualizer

click node_mnist "https://github.com/parm2006/neuralnetworksrust/blob/main/mnist.rs"
click node_test_eval "https://github.com/parm2006/neuralnetworksrust/blob/main/mnist.rs"
click node_single_inference "https://github.com/parm2006/neuralnetworksrust/blob/main/mnist.rs"
click node_python_visualizer "https://github.com/parm2006/neuralnetworksrust/blob/main/infer.py"
click node_tensor "https://github.com/parm2006/neuralnetworksrust/blob/main/src/tensor/tensor.rs"
click node_module_trait "https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/module.rs"
click node_sequential "https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/sequential.rs"
click node_linear "https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/linear.rs"
click node_flatten "https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/flatten.rs"
click node_activations "https://github.com/parm2006/neuralnetworksrust/tree/main/src/modules"
click node_loss_api "https://github.com/parm2006/neuralnetworksrust/blob/main/src/losses/loss.rs"
click node_cross_entropy "https://github.com/parm2006/neuralnetworksrust/blob/main/src/losses/cross_entropy.rs"
click node_other_losses "https://github.com/parm2006/neuralnetworksrust/tree/main/src/losses"
click node_optimizer_api "https://github.com/parm2006/neuralnetworksrust/blob/main/src/optim/optimizer.rs"
click node_sgd "https://github.com/parm2006/neuralnetworksrust/blob/main/src/optim/sgd.rs"
click node_adamw "https://github.com/parm2006/neuralnetworksrust/blob/main/src/optim/adamw.rs"
click node_checkpoint "https://github.com/parm2006/neuralnetworksrust/blob/main/parm_mnist_model.bin"

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_mnist,node_test_eval,node_single_inference,node_python_visualizer,node_user toneBlue
class node_tensor toneAmber
class node_module_trait,node_sequential,node_linear,node_flatten,node_activations toneMint
class node_loss_api,node_cross_entropy,node_other_losses,node_optimizer_api,node_sgd,node_adamw toneRose
class node_checkpoint,node_dataset toneIndigo
```

## Components

### MNIST workflows

- [Train and inference](https://github.com/parm2006/neuralnetworksrust/blob/main/mnist.rs): `mnist.rs`
- [Evaluation](https://github.com/parm2006/neuralnetworksrust/blob/main/mnist.rs): `mnist.rs`
- [Single inference](https://github.com/parm2006/neuralnetworksrust/blob/main/mnist.rs): `mnist.rs`
- [Python visualizer](https://github.com/parm2006/neuralnetworksrust/blob/main/infer.py): `infer.py`

### Tensor runtime

- [Tensor and autograd](https://github.com/parm2006/neuralnetworksrust/blob/main/src/tensor/tensor.rs): `src/tensor/tensor.rs`

### Model components

- [Module and state API](https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/module.rs): `src/modules/module.rs`
- [Sequential model](https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/sequential.rs): `src/modules/sequential.rs`
- [Linear layer](https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/linear.rs): `src/modules/linear.rs`
- [Flatten layer](https://github.com/parm2006/neuralnetworksrust/blob/main/src/modules/flatten.rs): `src/modules/flatten.rs`
- [Activations](https://github.com/parm2006/neuralnetworksrust/tree/main/src/modules): `src/modules`

### Training components

- [Loss API](https://github.com/parm2006/neuralnetworksrust/blob/main/src/losses/loss.rs): `src/losses/loss.rs`
- [Cross entropy](https://github.com/parm2006/neuralnetworksrust/blob/main/src/losses/cross_entropy.rs): `src/losses/cross_entropy.rs`
- [MSE and NLL](https://github.com/parm2006/neuralnetworksrust/tree/main/src/losses): `src/losses`
- [Optimizer API](https://github.com/parm2006/neuralnetworksrust/blob/main/src/optim/optimizer.rs): `src/optim/optimizer.rs`
- [SGD](https://github.com/parm2006/neuralnetworksrust/blob/main/src/optim/sgd.rs): `src/optim/sgd.rs`
- [AdamW](https://github.com/parm2006/neuralnetworksrust/blob/main/src/optim/adamw.rs): `src/optim/adamw.rs`

### Model persistence

- [Binary checkpoint](https://github.com/parm2006/neuralnetworksrust/blob/main/parm_mnist_model.bin): `parm_mnist_model.bin`

### Other components

- **User**
- **MNIST files**

## Connections

- User → Train and inference: starts
- Train and inference → MNIST files: reads training data
- Train and inference → Sequential model: builds model
- Train and inference → Cross entropy: computes loss
- Train and inference → AdamW: updates parameters
- Train and inference → Evaluation: evaluates after training
- Evaluation → MNIST files: reads test data
- Evaluation → Sequential model: runs forward pass
- Evaluation → Cross entropy: computes test loss
- Train and inference → Single inference: selects sample mode
- Single inference → MNIST files: reads test sample
- Single inference → Sequential model: runs forward pass
- Single inference → Binary checkpoint: loads weights
- Train and inference → Binary checkpoint: saves weights
- Train and inference → Tensor and autograd: creates batches and backpropagates
- Sequential model → Module and state API: implements module API
- Module and state API → Tensor and autograd: tracks parameters and state
- Sequential model → Linear layer: contains layers
- Sequential model → Flatten layer: contains layers
- Sequential model → Activations: contains activations
- Cross entropy → Loss API: implements
- MSE and NLL → Loss API: implements
- Cross entropy → Tensor and autograd: builds differentiable loss
- AdamW → Optimizer API: implements
- SGD → Optimizer API: implements
- AdamW → Tensor and autograd: reads gradients and updates data
- SGD → Tensor and autograd: reads gradients and updates data
- User → Python visualizer: launches optional viewer