# ymahlau/fdtdx architecture

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

- Interactive diagram: https://gitdiagram.com/ymahlau/fdtdx
- Repository: https://github.com/ymahlau/fdtdx

## Overview

##### Project Type and Purpose
- This is an open-source Python library (fdtdx) for Finite-Difference Time-Domain (FDTD) electromagnetic simulations built on JAX.
- Its purpose is to provide GPU-accelerated, differentiable simulation kernels plus convenient APIs for defining grids, materials, sources, detectors, and post-processing.

##### High-Level Architectural Components
a. User Layer (light gray)
- Example scripts or user code that import fdtdx API, configure simulations, run forward/backward passes, collect results, and plot.
b. API & Configuration (blue)
- `src/fdtdx/config.py`
- `src/fdtdx/constants.py`
- Entry points for simulation setup (grid size, time steps, boundary conditions).
c. Core Computational Engine (green)
- FDTD kernel modules under `src/fdtdx/fdtd/`
- forward/backward passes, update rules, initialization, container, wrapper
- Core utilities under `src/fdtdx/core/`
- grid discretization, linalg helpers, physics operators (curl, losses, modes), null/ misc backends
- JAX backend (external): JIT, automatic differentiation, XLA execution on CPU/GPU/TPU
d. Object Model (orange)
- `src/fdtdx/objects/`
- devices, sources, detectors, static materials, boundaries
- Each object exposes parameters (geometry, permittivity) that feed into the FDTD grid.
e. Interfaces & Recording (purple)
- `src/fdtdx/interfaces/`
- recorder, state management, modules, time filters
- Glue between engine iterations and high-level user calls.
f. Conversion & I/O (yellow)
- `src/fdtdx/conversion/` (JSON, STL exports)
- `src/fdtdx/utils/logger.py`, `plot_setup.py` for runtime reporting and plotting setup.
g. Visualization & Post-Processing (teal)
- `src/fdtdx/core/plotting/` + `objects/detectors/plotting/`
- Line plots, 2D plots, videos.

##### Relationships and Data Flow
- User code → calls API & config → builds object graph → passes to Core Engine
- Core Engine ↔ JAX (autodiff, JIT) → executes on CPU/GPU
- During each time step: Core Engine emits field states → Interfaces record/select data → Detectors process signals → Results returned to user

##### Architectural Patterns & Principles
- Modular layering: separation of setup (config/API), computation (engine), modelling (objects), I/O (conversion), and visualization.
- Functional core: pure functions in `core/` and `fdtd/` suitable for JAX transformations.
- Dependency injection via interfaces/recorder for flexible data capture without modifying core loops.
- Grouping of low-level physics routines vs. high-level user constructs.

##### Technologies & External Dependencies
- Python 3.8+
- JAX (XLA, JIT, automatic differentiation)
- NumPy (via JAX)
- Matplotlib (plotting utilities)
- JSON/STL parsers for conversion
- CI/CD: GitHub Actions, ReadTheDocs for documentation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User Layer\n(examples/)"]:::user
    click User "https://github.com/ymahlau/fdtdx/tree/main/examples/"

    %% API & Configuration
    subgraph "API & Configuration"
        Config["config.py"]:::api
        Constants["constants.py"]:::api
    end
    click Config "https://github.com/ymahlau/fdtdx/blob/main/src/fdtdx/config.py"
    click Constants "https://github.com/ymahlau/fdtdx/blob/main/src/fdtdx/constants.py"

    %% Object Model
    subgraph "Object Model"
        Objects["Objects\n(src/fdtdx/objects/)"]:::objects
    end
    click Objects "https://github.com/ymahlau/fdtdx/tree/main/src/fdtdx/objects/"

    %% Core Computational Engine
    subgraph "Core Computational Engine"
        FDTD["FDTD Kernels\n(src/fdtdx/fdtd/)"]:::engine
        CoreUtil["Core Utilities\n(src/fdtdx/core/)"]:::engine
    end
    click FDTD "https://github.com/ymahlau/fdtdx/tree/main/src/fdtdx/fdtd/"
    click CoreUtil "https://github.com/ymahlau/fdtdx/tree/main/src/fdtdx/core/"

    %% JAX Runtime
    JAX["JAX Runtime\n(JIT, XLA, Autodiff)"]:::external

    %% Interfaces & Recording
    subgraph "Interfaces & Recording"
        Modules["modules.py"]:::interfaces
        Recorder["recorder.py"]:::interfaces
        State["state.py"]:::interfaces
        TimeFilter["time_filter.py"]:::interfaces
    end
    click Modules "https://github.com/ymahlau/fdtdx/blob/main/src/fdtdx/interfaces/modules.py"
    click Recorder "https://github.com/ymahlau/fdtdx/blob/main/src/fdtdx/interfaces/recorder.py"
    click State "https://github.com/ymahlau/fdtdx/blob/main/src/fdtdx/interfaces/state.py"
    click TimeFilter "https://github.com/ymahlau/fdtdx/blob/main/src/fdtdx/interfaces/time_filter.py"

    %% Conversion & I/O
    subgraph "Conversion & I/O"
        Conversion["conversion\n(src/fdtdx/conversion/)"]:::conversion
        Logger["logger.py"]:::conversion
        PlotSetup["plot_setup.py"]:::conversion
    end
    click Conversion "https://github.com/ymahlau/fdtdx/tree/main/src/fdtdx/conversion/"
    click Logger "https://github.com/ymahlau/fdtdx/blob/main/src/fdtdx/utils/logger.py"
    click PlotSetup "https://github.com/ymahlau/fdtdx/blob/main/src/fdtdx/utils/plot_setup.py"

    %% Visualization & Post-Processing
    subgraph "Visualization & Post-Processing"
        VizCore["Core Plotting\n(src/fdtdx/core/plotting/)"]:::viz
        VizDet["Detector Plotting\n(src/fdtdx/objects/detectors/plotting/)"]:::viz
    end
    click VizCore "https://github.com/ymahlau/fdtdx/tree/main/src/fdtdx/core/plotting/"
    click VizDet "https://github.com/ymahlau/fdtdx/tree/main/src/fdtdx/objects/detectors/plotting/"

    %% Relationships
    User -->|imports API| Config
    Config --> Objects
    Config --> FDTD
    Config --> CoreUtil
    Objects --> FDTD
    FDTD -->|uses| CoreUtil
    FDTD <-->|executes on| JAX
    CoreUtil <-->|supports| JAX
    FDTD -->|emits states| Modules
    Modules --> Recorder
    Recorder --> User
    Modules --> State
    Modules --> TimeFilter
    FDTD --> Conversion
    FDTD --> VizCore
    FDTD --> VizDet
    Conversion --> User
    VizCore --> User
    VizDet --> User

    %% Styles
    classDef user fill:#f0f0f0,stroke:#333;
    classDef api fill:#add8e6,stroke:#333;
    classDef engine fill:#a8e6a1,stroke:#333;
    classDef objects fill:#f4a261,stroke:#333;
    classDef interfaces fill:#b39ddb,stroke:#333;
    classDef conversion fill:#ffe066,stroke:#333;
    classDef viz fill:#4dd0e1,stroke:#333;
    classDef external fill:#cccccc,stroke:#333;
```
