How ymahlau/fdtdx works
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