# mcmahon-lab/physics-aware-training architecture

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

- Interactive diagram: https://gitdiagram.com/mcmahon-lab/physics-aware-training
- Repository: https://github.com/mcmahon-lab/physics-aware-training

## Overview

This repository is an educational demonstration of Physics-Aware Training (PAT) for simulated physical neural networks, rather than a conventional package. The main user workflow is to run a notebook example that constructs and trains a PNN for a classification or autodifferentiable-function task, then inspect its output; precomputed training artifacts are also present. The standalone Python files provide a generic PAT autograd-function builder and RK4 ODE helpers. The README says examples are largely self-contained notebooks, and their contents were not sampled, so links from those notebooks to the standalone helpers are not asserted.

Main entry points: [`pat.py`](https://github.com/mcmahon-lab/physics-aware-training/blob/main/pat.py) (PAT autograd builder), [`Example 1 MNIST classification with PNN.ipynb`](https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%201%20MNIST%20classification%20with%20PNN.ipynb) (MNIST PNN), [`Example 2 Fashion MNIST classification with PNN and PAT.ipynb`](https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%202%20Fashion%20MNIST%20classification%20with%20PNN%20and%20PAT.ipynb) (Fashion PNN), [`Example 3 Toy example of a PAT autodifferentiable function.ipynb`](https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%203%20Toy%20example%20of%20a%20PAT%20autodifferentiable%20function.ipynb) (PAT toy function)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_examples["Notebook examples"]
  node_mnist["MNIST PNN"]
  node_fashion["Fashion PNN"]
  node_toy["PAT toy function"]
end

subgraph group_runtime["Training runtime"]
  node_pat["PAT autograd builder<br/>[pat.py]"]
  node_ode["RK4 ODE solver<br/>[ode_utils.py]"]
end

subgraph group_artifacts["Training artifacts"]
  node_logs[("Precomputed results")]
end

node_user(("Learner"))

node_user -->|"runs example"| node_mnist
node_user -->|"runs example"| node_fashion
node_user -->|"runs example"| node_toy
node_mnist -.->|"uses PAT"| node_pat
node_fashion -.->|"uses PAT"| node_pat
node_toy -.->|"uses PAT"| node_pat

click node_mnist "https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%201%20MNIST%20classification%20with%20PNN.ipynb"
click node_fashion "https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%202%20Fashion%20MNIST%20classification%20with%20PNN%20and%20PAT.ipynb"
click node_toy "https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%203%20Toy%20example%20of%20a%20PAT%20autodifferentiable%20function.ipynb"
click node_pat "https://github.com/mcmahon-lab/physics-aware-training/blob/main/pat.py"
click node_ode "https://github.com/mcmahon-lab/physics-aware-training/blob/main/ode_utils.py"
click node_logs "https://github.com/mcmahon-lab/physics-aware-training/tree/main/training_logs/precomputed_results"

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_fashion,node_toy toneBlue
class node_pat,node_ode toneAmber
class node_logs toneMint
class node_user toneIndigo
```

## Components

### Notebook examples

- [MNIST PNN](https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%201%20MNIST%20classification%20with%20PNN.ipynb): `Example 1 MNIST classification with PNN.ipynb`
- [Fashion PNN](https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%202%20Fashion%20MNIST%20classification%20with%20PNN%20and%20PAT.ipynb): `Example 2 Fashion MNIST classification with PNN and PAT.ipynb`
- [PAT toy function](https://github.com/mcmahon-lab/physics-aware-training/blob/main/Example%203%20Toy%20example%20of%20a%20PAT%20autodifferentiable%20function.ipynb): `Example 3 Toy example of a PAT autodifferentiable function.ipynb`

### Training runtime

- [PAT autograd builder](https://github.com/mcmahon-lab/physics-aware-training/blob/main/pat.py): `pat.py`
- [RK4 ODE solver](https://github.com/mcmahon-lab/physics-aware-training/blob/main/ode_utils.py): `ode_utils.py`

### Training artifacts

- [Precomputed results](https://github.com/mcmahon-lab/physics-aware-training/tree/main/training_logs/precomputed_results): `training_logs/precomputed_results`

### Other components

- **Learner**

## Connections

- Learner → MNIST PNN: runs example (evidence: `README.md`)
- Learner → Fashion PNN: runs example (evidence: `README.md`)
- Learner → PAT toy function: runs example (evidence: `README.md`)
- MNIST PNN → PAT autograd builder: uses PAT
- Fashion PNN → PAT autograd builder: uses PAT
- PAT toy function → PAT autograd builder: uses PAT