# mcmahon-lab/2d-programmable-waveguide architecture

> Architecture diagram of the GitHub repository mcmahon-lab/2d-programmable-waveguide, 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/2d-programmable-waveguide
- Repository: https://github.com/mcmahon-lab/2d-programmable-waveguide

## Overview

This repository is a compact demo toolkit for simulating programmable 2D photonic waveguides and exploring inverse design, classification, multimode transformations, and physics-aware training. The user-facing workflow is to run a Jupyter example, define or optimize an index pattern and input field, then simulate propagation and inspect the output. The library supplies the propagation solver, waveguide geometry, mode and beam utilities, and training helpers. Notebook-to-module links follow the README’s descriptions; source-level edges are limited to relationships shown in the excerpts or SOURCE INDEX.

Main entry points: [`tdwg_lib/split_step_solver.py`](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/split_step_solver.py) (BPM propagation), [`Example 1 Y-splitter.ipynb`](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%201%20Y-splitter.ipynb) (Y-splitter), [`Example 2 Inverse design.ipynb`](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%202%20Inverse%20design.ipynb) (Inverse design), [`Example 3 MNIST classification.ipynb`](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%203%20MNIST%20classification.ipynb) (MNIST classification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_examples["Demonstration notebooks"]
  node_ysplit["Y-splitter"]
  node_inverse["Inverse design"]
  node_mnist["MNIST classification"]
  node_modeconv["Mode conversion"]
  node_mvm["Multimode MVM"]
  node_patdemo["Mismatched passes"]
end

subgraph group_physics["Waveguide physics"]
  node_waveguide["Waveguide geometry<br/>[waveguide.py]"]
  node_bpm["BPM propagation"]
  node_modes["Eigenmode solver<br/>[mode_solver.py]"]
  node_beams["Beam and mode fields<br/>[beam_utils.py]"]
end

subgraph group_numerics["Numerical utilities"]
  node_torchfft["PyTorch Fourier tools<br/>[ftutils_torch.py]"]
  node_numpyfft["NumPy Fourier tools<br/>[ftutils_np.py]"]
  node_smoothing["Smoothing helpers<br/>[helpers.py]"]
end

subgraph group_training["Design and training"]
  node_pat["PAT autograd<br/>[pat.py]"]
  node_pnn["Training utilities<br/>[pnn_utils.py]"]
end

node_user(("Researcher"))

node_user -->|"runs example"| node_ysplit
node_user -->|"runs example"| node_inverse
node_user -->|"runs example"| node_mnist
node_user -->|"runs example"| node_modeconv
node_user -->|"runs example"| node_mvm
node_user -->|"runs example"| node_patdemo
node_ysplit -->|"simulates propagation"| node_bpm
node_inverse -->|"optimizes simulation"| node_bpm
node_modeconv -->|"demonstrates propagation"| node_bpm
node_mvm -->|"designs transformation"| node_bpm
node_mnist -->|"classifies with waveguide"| node_bpm
node_patdemo -->|"uses PAT approach"| node_pat
node_waveguide -->|"builds frequency axis"| node_torchfft
node_bpm -->|"uses frequency axis"| node_torchfft
node_modes -->|"uses transforms"| node_numpyfft

click node_ysplit "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%201%20Y-splitter.ipynb"
click node_inverse "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%202%20Inverse%20design.ipynb"
click node_mnist "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%203%20MNIST%20classification.ipynb"
click node_modeconv "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%204%20Mode%20conversion%20in%20multimode%20waveguide.ipynb"
click node_mvm "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%205%20Matrix-vector-multiplication%20in%20multimode%20waveguide.ipynb"
click node_patdemo "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%206%20Mismatched%20forward-backward%20pass.ipynb"
click node_waveguide "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/waveguide.py"
click node_bpm "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/split_step_solver.py"
click node_modes "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/mode_solver.py"
click node_beams "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/beam_utils.py"
click node_torchfft "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/ftutils_torch.py"
click node_numpyfft "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/ftutils_np.py"
click node_smoothing "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/helpers.py"
click node_pat "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/pat.py"
click node_pnn "https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/pnn_utils.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_ysplit,node_inverse,node_mnist,node_modeconv,node_mvm,node_patdemo toneBlue
class node_waveguide,node_bpm,node_modes,node_beams toneAmber
class node_torchfft,node_numpyfft,node_smoothing toneMint
class node_pat,node_pnn toneRose
class node_user toneIndigo
```

## Components

### Demonstration notebooks

- [Y-splitter](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%201%20Y-splitter.ipynb): `Example 1 Y-splitter.ipynb`
- [Inverse design](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%202%20Inverse%20design.ipynb): `Example 2 Inverse design.ipynb`
- [MNIST classification](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%203%20MNIST%20classification.ipynb): `Example 3 MNIST classification.ipynb`
- [Mode conversion](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%204%20Mode%20conversion%20in%20multimode%20waveguide.ipynb): `Example 4 Mode conversion in multimode waveguide.ipynb`
- [Multimode MVM](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%205%20Matrix-vector-multiplication%20in%20multimode%20waveguide.ipynb): `Example 5 Matrix-vector-multiplication in multimode waveguide.ipynb`
- [Mismatched passes](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/Example%206%20Mismatched%20forward-backward%20pass.ipynb): `Example 6 Mismatched forward-backward pass.ipynb`

### Waveguide physics

- [Waveguide geometry](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/waveguide.py): `tdwg_lib/waveguide.py`
- [BPM propagation](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/split_step_solver.py): `tdwg_lib/split_step_solver.py`
- [Eigenmode solver](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/mode_solver.py): `tdwg_lib/mode_solver.py`
- [Beam and mode fields](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/beam_utils.py): `tdwg_lib/beam_utils.py`

### Numerical utilities

- [PyTorch Fourier tools](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/ftutils_torch.py): `tdwg_lib/ftutils_torch.py`
- [NumPy Fourier tools](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/ftutils_np.py): `tdwg_lib/ftutils_np.py`
- [Smoothing helpers](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/helpers.py): `tdwg_lib/helpers.py`

### Design and training

- [PAT autograd](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/pat.py): `tdwg_lib/pat.py`
- [Training utilities](https://github.com/mcmahon-lab/2d-programmable-waveguide/blob/master/tdwg_lib/pnn_utils.py): `tdwg_lib/pnn_utils.py`

### Other components

- **Researcher**

## Connections

- Researcher → Y-splitter: runs example (evidence: `README.md`)
- Researcher → Inverse design: runs example (evidence: `README.md`)
- Researcher → MNIST classification: runs example (evidence: `README.md`)
- Researcher → Mode conversion: runs example (evidence: `README.md`)
- Researcher → Multimode MVM: runs example (evidence: `README.md`)
- Researcher → Mismatched passes: runs example (evidence: `README.md`)
- Y-splitter → BPM propagation: simulates propagation (evidence: `README.md`)
- Inverse design → BPM propagation: optimizes simulation (evidence: `README.md`)
- Mode conversion → BPM propagation: demonstrates propagation (evidence: `README.md`)
- Multimode MVM → BPM propagation: designs transformation (evidence: `README.md`)
- MNIST classification → BPM propagation: classifies with waveguide (evidence: `README.md`)
- Mismatched passes → PAT autograd: uses PAT approach (evidence: `README.md`)
- Waveguide geometry → PyTorch Fourier tools: builds frequency axis (evidence: `tdwg_lib/waveguide.py`)
- BPM propagation → PyTorch Fourier tools: uses frequency axis (evidence: `tdwg_lib/split_step_solver.py`)
- Eigenmode solver → NumPy Fourier tools: uses transforms (evidence: `tdwg_lib/mode_solver.py`)