# scopex-asu/maps architecture

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

- Interactive diagram: https://gitdiagram.com/scopex-asu/maps
- Repository: https://github.com/scopex-asu/maps

## Overview

MAPS combines photonic device inverse design, numerical simulation, labeled-data generation, and AI model training. A typical workflow defines a device and optimization objective, evaluates fields and gradients with a physics solver, updates the design, and can generate simulation datasets for training predictors that may accelerate later design. The README documents FDFD, 3D FDTD, and thermo-optical capabilities; sampled source confirms selected solver and optimization behavior, but not every subsystem’s runtime wiring.

Main entry points: [`core/invdes/models/base_optimization.py`](https://github.com/scopex-asu/maps/blob/main/core/invdes/models/base_optimization.py) (Optimization plan), [`core/train/builder.py`](https://github.com/scopex-asu/maps/blob/main/core/train/builder.py) (Training builder), [`core/invdes/invdesign.py`](https://github.com/scopex-asu/maps/blob/main/core/invdes/invdesign.py) (Design runner), [`core/train/trainer.py`](https://github.com/scopex-asu/maps/blob/main/core/train/trainer.py) (Trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Inverse design"]
  node_device["Device models"]
  node_opt["Optimization plan"]
  node_runner["Design runner<br/>[invdesign.py]"]
  node_optimizers["Optimizers"]
end

subgraph group_physics["Physics simulation"]
  node_fdfd["FDFD solver"]
  node_fdtd["FDTD solver"]
  node_heat["Heat solver"]
  node_ceviche["Ceviche backend"]
end

subgraph group_data["Dataset generation"]
  node_dataset_launch["Dataset launcher"]
  node_generators["Device generators"]
end

subgraph group_learning["AI training"]
  node_dataset["FDFD dataset<br/>[fdfd.py]"]
  node_builder["Training builder<br/>[builder.py]"]
  node_models["Predictor models"]
  node_trainer["Trainer<br/>[trainer.py]"]
end

node_user(("Engineer"))
node_fdtdx["fdtdx runtime"]

node_user -->|"configures design"| node_runner
node_runner -->|"runs optimization"| node_opt
node_runner -->|"builds optimizer"| node_optimizers
node_opt -->|"evaluates device"| node_device
node_opt -->|"solves fields"| node_fdfd
node_opt -.->|"co-simulates heat"| node_heat
node_opt -.->|"solves FDTD"| node_fdtd
node_fdfd -->|"uses backend"| node_ceviche
node_fdtd -.->|"invokes runtime"| node_fdtdx
node_user -->|"requests data"| node_dataset_launch
node_dataset_launch -->|"dispatches generation"| node_generators
node_generators -->|"simulates devices"| node_fdfd
node_user -->|"configures training"| node_builder
node_builder -->|"loads samples"| node_dataset
node_builder -->|"constructs model"| node_models
node_builder -->|"constructs trainer"| node_trainer
node_trainer -->|"trains predictor"| node_models
node_trainer -->|"consumes batches"| node_dataset
node_models -.->|"accelerates design"| node_opt

click node_device "https://github.com/scopex-asu/maps/tree/main/core/invdes/models/layers"
click node_opt "https://github.com/scopex-asu/maps/blob/main/core/invdes/models/base_optimization.py"
click node_runner "https://github.com/scopex-asu/maps/blob/main/core/invdes/invdesign.py"
click node_optimizers "https://github.com/scopex-asu/maps/tree/main/core/invdes/optimizer"
click node_fdfd "https://github.com/scopex-asu/maps/tree/main/core/fdfd"
click node_fdtd "https://github.com/scopex-asu/maps/tree/main/core/fdtd"
click node_heat "https://github.com/scopex-asu/maps/tree/main/core/heat"
click node_ceviche "https://github.com/scopex-asu/maps/tree/main/thirdparty/ceviche"
click node_dataset_launch "https://github.com/scopex-asu/maps/blob/main/data/fdfd/dataset_generation_launcher.py"
click node_generators "https://github.com/scopex-asu/maps/tree/main/data/fdfd"
click node_dataset "https://github.com/scopex-asu/maps/blob/main/core/train/datasets/fdfd.py"
click node_builder "https://github.com/scopex-asu/maps/blob/main/core/train/builder.py"
click node_models "https://github.com/scopex-asu/maps/tree/main/core/train/models"
click node_trainer "https://github.com/scopex-asu/maps/blob/main/core/train/trainer.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_device,node_opt,node_runner,node_optimizers toneBlue
class node_fdfd,node_fdtd,node_heat,node_ceviche toneAmber
class node_dataset_launch,node_generators toneMint
class node_dataset,node_builder,node_models,node_trainer toneRose
class node_user,node_fdtdx toneIndigo
```

## Components

### Inverse design

- [Device models](https://github.com/scopex-asu/maps/tree/main/core/invdes/models/layers): `core/invdes/models/layers`
- [Optimization plan](https://github.com/scopex-asu/maps/blob/main/core/invdes/models/base_optimization.py): `core/invdes/models/base_optimization.py`
- [Design runner](https://github.com/scopex-asu/maps/blob/main/core/invdes/invdesign.py): `core/invdes/invdesign.py`
- [Optimizers](https://github.com/scopex-asu/maps/tree/main/core/invdes/optimizer): `core/invdes/optimizer`

### Physics simulation

- [FDFD solver](https://github.com/scopex-asu/maps/tree/main/core/fdfd): `core/fdfd`
- [FDTD solver](https://github.com/scopex-asu/maps/tree/main/core/fdtd): `core/fdtd`
- [Heat solver](https://github.com/scopex-asu/maps/tree/main/core/heat): `core/heat`
- [Ceviche backend](https://github.com/scopex-asu/maps/tree/main/thirdparty/ceviche): `thirdparty/ceviche`

### Dataset generation

- [Dataset launcher](https://github.com/scopex-asu/maps/blob/main/data/fdfd/dataset_generation_launcher.py): `data/fdfd/dataset_generation_launcher.py`
- [Device generators](https://github.com/scopex-asu/maps/tree/main/data/fdfd): `data/fdfd`

### AI training

- [FDFD dataset](https://github.com/scopex-asu/maps/blob/main/core/train/datasets/fdfd.py): `core/train/datasets/fdfd.py`
- [Training builder](https://github.com/scopex-asu/maps/blob/main/core/train/builder.py): `core/train/builder.py`
- [Predictor models](https://github.com/scopex-asu/maps/tree/main/core/train/models): `core/train/models`
- [Trainer](https://github.com/scopex-asu/maps/blob/main/core/train/trainer.py): `core/train/trainer.py`

### Other components

- **Engineer**
- **fdtdx runtime**

## Connections

- Engineer → Design runner: configures design
- Design runner → Optimization plan: runs optimization
- Design runner → Optimizers: builds optimizer
- Optimization plan → Device models: evaluates device
- Optimization plan → FDFD solver: solves fields
- Optimization plan → Heat solver: co-simulates heat
- Optimization plan → FDTD solver: solves FDTD
- FDFD solver → Ceviche backend: uses backend
- FDTD solver → fdtdx runtime: invokes runtime
- Engineer → Dataset launcher: requests data
- Dataset launcher → Device generators: dispatches generation
- Device generators → FDFD solver: simulates devices
- Engineer → Training builder: configures training
- Training builder → FDFD dataset: loads samples
- Training builder → Predictor models: constructs model
- Training builder → Trainer: constructs trainer
- Trainer → Predictor models: trains predictor
- Trainer → FDFD dataset: consumes batches
- Predictor models → Optimization plan: accelerates design