rfx-fdtd 1.0.0__tar.gz

rfx_fdtd-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,48 @@
+# NOTE: pyproject.toml has [project.optional-dependencies].dev (pytest, pytest-xdist)
+# but no "test" extra. If you want a dedicated test extra, add to pyproject.toml:
+#   test = ["pytest>=7.0", "optax"]
+# Until then, this workflow uses .[dev] to get pytest.
+name: test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - run: pip install ruff
+      - run: ruff check rfx/ tests/ --select E,F,W --ignore E501
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: >
+          pytest -x -q
+          --ignore=tests/test_meep_crossval.py
+          --ignore=tests/test_meep_crossval_patch.py
+          --ignore=tests/test_openems_crossval.py
+          --ignore=tests/test_crossval_comprehensive.py
+          --ignore=tests/test_subpixel.py
+          -k "not slow"

rfx_fdtd-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.omc/
+.omx/
+docs-site/
+CLAUDE.md
+AGENTS.md
+
+# Internal development artifacts (not for public repo)
+docs/research_notes/
+docs/codex_specs/
+docs/reports/
+docs/superpowers/
+examples/vessl_*.yaml
+examples/benchmark_jax_vs_numpy.py
+
+# Generated plots (examples produce these at runtime)
+examples/*.png

rfx_fdtd-1.0.0/ATTRIBUTION.md

@@ -0,0 +1,46 @@
+# rfx Attribution & Licenses
+
+## Core FDTD Algorithm
+- **Yee algorithm**: K. S. Yee, "Numerical solution of initial boundary value problems involving Maxwell's equations in isotropic media", IEEE TAP, 1966.
+- **License**: Public domain (fundamental algorithm, no copyright)
+
+## PML / CPML
+- **CFS-CPML**: J. A. Roden and S. D. Gedney, "Convolution PML (CPML): An efficient FDTD implementation of the CFS-PML for arbitrary media", Microwave and Optical Technology Letters, 27(5), 2000.
+- **License**: Algorithm is public; implementation is original rfx code (MIT)
+
+## SBP-SAT Subgridding
+- **Reference**: B. Cheng, R. E. Diaz, et al., "Toward the Development of a 3-D SBP-SAT FDTD Method: Subgridding Implementation", IEEE Transactions on Antennas and Propagation, 2025 (DOI: 10.1109/TAP.2025.10836194)
+- **License**: Algorithm from published paper; implementation is original rfx code (MIT)
+- **Note**: SBP (Summation-By-Parts) operators and SAT (Simultaneous Approximation Terms) are general numerical methods from the finite difference community. Cheng et al. applied them to FDTD subgridding.
+
+## Harminv / Matrix Pencil Method
+- **FDM reference**: V. A. Mandelshtam and H. S. Taylor, "Harmonic inversion of time signals and its applications", J. Chem. Phys. 107, 6756, 1997.
+- **MPM reference**: T. K. Sarkar and O. Pereira, "Using the Matrix Pencil Method to Estimate the Parameters of a Sum of Complex Exponentials", IEEE Antennas and Propagation Magazine, Feb 1995.
+- **License**: Both are published algorithms; implementation is original rfx code (MIT)
+- **Note**: Meep uses Harminv (Steven G. Johnson, MIT License) which implements FDM. rfx implements MPM independently — different algorithm, same purpose.
+
+## Subpixel Smoothing
+- **Reference**: A. Farjadpour et al., "Improving accuracy by subpixel smoothing in the finite-difference time domain", Optics Letters, 31(20), 2006.
+- **License**: Algorithm from published paper; implementation is original (MIT)
+
+## Near-to-Far-Field Transform
+- **Reference**: A. Taflove and S. C. Hagness, "Computational Electrodynamics: The Finite-Difference Time-Domain Method", 3rd edition, Chapter 8.
+- **License**: Standard FDTD technique; implementation is original (MIT)
+
+## Thin Wire Model
+- **Reference**: R. Holland, "Finite-Difference Analysis of EMP Coupling to Thin Struts and Wires", IEEE EMC, 1981.
+- **License**: Published algorithm; implementation is original (MIT)
+
+## Software Dependencies
+- **JAX** (Google): Apache 2.0 License
+- **NumPy**: BSD 3-Clause License
+- **SciPy**: BSD 3-Clause License
+- **matplotlib**: PSF License (BSD-compatible)
+- **pyvista** (optional): MIT License
+
+## rfx License
+rfx is released under the **MIT License**.
+
+## Development
+- Primary development: Claude Opus 4.6 (Anthropic) + Codex (OpenAI)
+- Supervision: Prof. Byungkwan Kim, REMI Lab, Chungnam National University

rfx_fdtd-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Byungkwan Kim, REMI Lab, Chungnam National University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rfx_fdtd-1.0.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.2
+Name: rfx-fdtd
+Version: 1.0.0
+Summary: JAX-native 3D FDTD electromagnetic simulator for RF engineering
+Author-email: REMI Lab <byungkwan.kim@cnu.ac.kr>
+License: MIT
+Keywords: fdtd,electromagnetics,jax,rf,simulation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jax>=0.4.20
+Requires-Dist: jaxlib>=0.4.20
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.11
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: h5py>=3.8
+Provides-Extra: optimization
+Requires-Dist: optax>=0.1.7; extra == "optimization"
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.7; extra == "visualization"
+Requires-Dist: pillow; extra == "visualization"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: all
+Requires-Dist: rfx[dev,optimization,visualization]; extra == "all"
+
+# rfx
+
+```text
+██████╗ ███████╗██╗  ██╗
+██╔══██╗██╔════╝╚██╗██╔╝
+██████╔╝█████╗   ╚███╔╝
+██╔══██╗██╔══╝   ██╔██╗
+██║  ██║██║     ██╔╝ ██╗
+╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝
+```
+
+**Differentiable 3D FDTD electromagnetic simulator for RF and microwave engineering — powered by JAX.**
+
+**v1.0.0** -- Production-stable release with 260+ tests and 0.000% cross-validation agreement vs OpenEMS.
+
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Tests](https://github.com/BK3536/rfx/actions/workflows/test.yml/badge.svg)](https://github.com/BK3536/rfx/actions)
+[![Docs](https://img.shields.io/badge/docs-remilab.ai%2Frfx-blue)](https://remilab.ai/rfx/)
+
+## v1.0.0 Highlights
+
+- **Non-uniform z mesh** via `dz_profile` for thin substrates
+- **SBP-SAT subgridding** research path with JIT support
+- **Lumped RLC elements** (series / parallel)
+- **Via** and **CurvedPatch** geometry helpers
+- **Oblique-incidence TFSF** plane-wave source
+- **Field animation export** via `save_field_animation`
+- **Auto-configuration** from geometry + frequency range
+- **260+ tests** with strong cavity/waveguide benchmarking and active antenna validation work
+
+## At a Glance
+
+| | |
+|---|---|
+| **GPU-accelerated** | ~3,000 Mcells/s on RTX 4090 via `jax.lax.scan` JIT |
+| **Differentiable** | `jax.grad` through full time-stepping for inverse design |
+| **Benchmarked** | Strong agreement vs Meep/OpenEMS on core cavity and waveguide cases |
+| **Non-uniform mesh** | Graded z-profiles for thin substrates without global refinement |
+| **Auto-configuration** | `auto_configure()` derives dx, domain, CPML, timesteps from geometry |
+| **Lumped RLC** | Series, parallel, and shunt lumped elements in any cell |
+| **Via & curved patch** | First-class geometry primitives for PCB and antenna design |
+| **Animation** | Time-domain field animation export (MP4/GIF) |
+
+## Installation
+
+```bash
+# From source (recommended)
+git clone https://github.com/BK3536/rfx.git
+cd rfx
+pip install -e ".[dev]"
+```
+
+> **GPU:** Complete the [JAX GPU setup](https://jax.readthedocs.io/en/latest/installation.html) for your platform before running large simulations.
+
+## Quick Start
+
+```python
+from rfx import Simulation, Box, GaussianPulse
+import numpy as np
+
+# PEC cavity with dielectric slab — simulate up to 10 GHz
+sim = Simulation(freq_max=10e9, domain=(0.048, 0.032, 0.032), boundary="pec")
+sim.add_material("slab", eps_r=2.2)
+sim.add(Box((0.016, 0, 0), (0.032, 0.032, 0.032)), material="slab")
+
+# Lumped port + probe
+sim.add_port(
+    (0.006, 0.016, 0.016),
+    "ez",
+    impedance=50.0,
+    waveform=GaussianPulse(f0=5e9, bandwidth=0.8),
+)
+sim.add_probe((0.042, 0.016, 0.016), "ez")
+
+result = sim.run(num_periods=30)
+
+# S11
+s11_dB = 20 * np.log10(np.abs(result.s_params[0, 0, :]) + 1e-12)
+```
+
+## Patch Antenna with Non-Uniform Mesh
+
+```python
+from rfx import Simulation, Box, GaussianPulse, auto_configure
+import numpy as np
+
+# Auto-configure from geometry and frequency range
+geometry = [
+    (Box((0, 0, 0), (0.06, 0.06, 0.0016)), "fr4"),
+    (Box((0, 0, 0), (0.06, 0.06, 0)), "pec"),
+    (Box((0.015, 0.011, 0.0016), (0.0444, 0.049, 0.0016)), "pec"),
+]
+materials = {"fr4": {"eps_r": 4.4, "sigma": 0.025}, "pec": {"eps_r": 1.0, "sigma": 1e10}}
+config = auto_configure(geometry, (1e9, 4e9), materials=materials, accuracy="standard")
+print(config.summary())  # Shows dx, non-uniform dz, CPML, n_steps
+
+# Build simulation from auto-config
+sim = Simulation(**config.to_sim_kwargs())
+sim.add_material("fr4", eps_r=4.4, sigma=0.025)
+for shape, mat in geometry:
+    sim.add(shape, material=mat)
+sim.add_source((0.025, 0.03, 0.0008), "ez", waveform=GaussianPulse(f0=2.4e9))
+sim.add_probe((0.025, 0.03, 0.0008), "ez")
+
+result = sim.run(n_steps=config.n_steps)
+modes = result.find_resonances(freq_range=(1.5e9, 3.5e9))
+for m in modes:
+    print(f"f={m.freq/1e9:.4f} GHz, Q={m.Q:.0f}")
+```
+
+## Inverse Design
+
+```python
+from rfx import Simulation, Box, GaussianPulse
+from rfx.optimize import DesignRegion, optimize
+from rfx.optimize_objectives import minimize_s11
+
+sim = Simulation(freq_max=10e9, domain=(0.048, 0.032, 0.032), boundary="pec")
+sim.add_port((0.006, 0.016, 0.016), "ez", impedance=50.0,
+             waveform=GaussianPulse(f0=5e9, bandwidth=0.8))
+
+region = DesignRegion(
+    corner_lo=(0.016, 0.008, 0.008),
+    corner_hi=(0.032, 0.024, 0.024),
+    eps_range=(1.0, 4.4),
+)
+
+result = optimize(sim, region, minimize_s11, n_iters=40, lr=0.05)
+print(f"Final loss: {result.loss_history[-1]:.4f}")
+```
+
+## Key Features
+
+### Simulation Engine
+- 3D/2D Yee solver with CFS-CPML absorbing boundaries
+- True PEC mask (component-specific tangential zeroing)
+- Non-uniform z mesh for thin substrates
+- SBP-SAT subgridding research path
+- Periodic boundaries and oblique-incidence TFSF plane-wave source
+- Auto-configuration: `auto_configure()` derives dx, domain, CPML, timesteps, and source recommendation
+- Lumped RLC elements (series and parallel topologies)
+
+### Geometry
+- CSG primitives: Box, Sphere, Cylinder
+- CurvedPatch for staircase-approximated curved antenna layouts
+- Via for PCB through-hole / plated interconnect modeling
+
+### Sources & Ports
+- GaussianPulse, ModulatedGaussian, CW, custom waveforms
+- Soft sources and polarized sources
+- Lumped ports and multi-cell wire ports (conductor-to-conductor)
+- Waveguide ports with modal decomposition (eigenmode solver)
+- Polarized sources (Jones vector: circular, LHCP, slant45)
+
+### Materials
+- Dispersive: Debye, Lorentz/Drude
+- Magnetic (`mu_r` validated)
+- Thin conductors with subcell correction
+- Subpixel smoothing (Farjadpour/Kottke)
+- Built-in library: `pec`, `fr4`, `rogers4003c`, `copper`, `alumina`, `ptfe`, `water_20c`, and others
+
+### Analysis
+- S-parameters: lumped, wire (JIT-DFT), waveguide (N-port matrix)
+- Harminv resonance extraction (Matrix Pencil Method)
+- NTFF far-field, radiation patterns, RCS
+- Far-field polarization (axial ratio, tilt, sense)
+- Touchstone I/O, HDF5 checkpoints, VTK export
+- Time-domain field animation (MP4/GIF via `save_field_animation`)
+
+### Optimization
+- Design regions with `jax.grad` through full simulation
+- Adam optimizer, gradient checkpointing
+- Objective library: `minimize_s11`, `maximize_s21`, `target_impedance`, `maximize_bandwidth`, `maximize_directivity`
+
+## Benchmark Snapshot
+
+Core benchmark areas currently documented most strongly:
+
+| Geometry | rfx vs Meep | rfx vs OpenEMS | rfx vs Analytical |
+|----------|-------------|----------------|-------------------|
+| PEC cavity TM110 | 0.010% | **0.000%** | 0.013% |
+| FR4 cavity (eps=4.4) | 0.006% | — | 0.013% |
+| Rogers (eps=3.55) | 0.007% | — | 0.026% |
+| PTFE (eps=2.2) | 0.004% | — | 0.004% |
+| Alumina (eps=9.8) | 0.005% | — | 0.038% |
+
+Patch/microstrip resonance workflows are also active, but feed/port
+interpretation should be documented more carefully than the cavity/waveguide
+benchmarks.
+
+## GPU Performance (RTX 4090)
+
+| Grid | Steps | Time | Throughput |
+|------|-------|------|------------|
+| 23^3 | 200 | 0.087s | 28 Mcells/s |
+| 33^3 | 300 | 0.086s | 125 Mcells/s |
+| 43^3 | 400 | 0.103s | 310 Mcells/s |
+| 63^3 | 500 | 0.095s | 1,310 Mcells/s |
+
+Gradient (reverse-mode AD): ~0.31s for all grid sizes.
+
+## Documentation
+
+Full documentation: **[remilab.ai/rfx](https://remilab.ai/rfx/)** and
+repo-local guides under [`docs/guide/`](docs/guide/index.md).
+
+- [User Guide](https://remilab.ai/rfx/guide/) — Installation, API, materials, sources, probes
+- [AI Agent Guide](https://remilab.ai/rfx/agent/) — Auto-configuration, prompt templates, design workflows
+
+## Citation
+
+```bibtex
+@software{kim_rfx_2026,
+  author       = {Byungkwan Kim},
+  title        = {rfx: JAX-based differentiable 3D FDTD simulator},
+  institution  = {REMI Lab, Chungnam National University},
+  year         = {2026},
+  url          = {https://github.com/BK3536/rfx}
+}
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Acknowledgments
+
+Developed by [Byungkwan Kim](https://remilab.cnu.ac.kr) at the **Radar & ElectroMagnetic Intelligence (REMI) Laboratory**, Chungnam National University.
+
+AI-assisted development: Claude (Anthropic), Codex (OpenAI).

rfx_fdtd-1.0.0/README.md

@@ -0,0 +1,230 @@
+# rfx
+
+```text
+██████╗ ███████╗██╗  ██╗
+██╔══██╗██╔════╝╚██╗██╔╝
+██████╔╝█████╗   ╚███╔╝
+██╔══██╗██╔══╝   ██╔██╗
+██║  ██║██║     ██╔╝ ██╗
+╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝
+```
+
+**Differentiable 3D FDTD electromagnetic simulator for RF and microwave engineering — powered by JAX.**
+
+**v1.0.0** -- Production-stable release with 260+ tests and 0.000% cross-validation agreement vs OpenEMS.
+
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Tests](https://github.com/BK3536/rfx/actions/workflows/test.yml/badge.svg)](https://github.com/BK3536/rfx/actions)
+[![Docs](https://img.shields.io/badge/docs-remilab.ai%2Frfx-blue)](https://remilab.ai/rfx/)
+
+## v1.0.0 Highlights
+
+- **Non-uniform z mesh** via `dz_profile` for thin substrates
+- **SBP-SAT subgridding** research path with JIT support
+- **Lumped RLC elements** (series / parallel)
+- **Via** and **CurvedPatch** geometry helpers
+- **Oblique-incidence TFSF** plane-wave source
+- **Field animation export** via `save_field_animation`
+- **Auto-configuration** from geometry + frequency range
+- **260+ tests** with strong cavity/waveguide benchmarking and active antenna validation work
+
+## At a Glance
+
+| | |
+|---|---|
+| **GPU-accelerated** | ~3,000 Mcells/s on RTX 4090 via `jax.lax.scan` JIT |
+| **Differentiable** | `jax.grad` through full time-stepping for inverse design |
+| **Benchmarked** | Strong agreement vs Meep/OpenEMS on core cavity and waveguide cases |
+| **Non-uniform mesh** | Graded z-profiles for thin substrates without global refinement |
+| **Auto-configuration** | `auto_configure()` derives dx, domain, CPML, timesteps from geometry |
+| **Lumped RLC** | Series, parallel, and shunt lumped elements in any cell |
+| **Via & curved patch** | First-class geometry primitives for PCB and antenna design |
+| **Animation** | Time-domain field animation export (MP4/GIF) |
+
+## Installation
+
+```bash
+# From source (recommended)
+git clone https://github.com/BK3536/rfx.git
+cd rfx
+pip install -e ".[dev]"
+```
+
+> **GPU:** Complete the [JAX GPU setup](https://jax.readthedocs.io/en/latest/installation.html) for your platform before running large simulations.
+
+## Quick Start
+
+```python
+from rfx import Simulation, Box, GaussianPulse
+import numpy as np
+
+# PEC cavity with dielectric slab — simulate up to 10 GHz
+sim = Simulation(freq_max=10e9, domain=(0.048, 0.032, 0.032), boundary="pec")
+sim.add_material("slab", eps_r=2.2)
+sim.add(Box((0.016, 0, 0), (0.032, 0.032, 0.032)), material="slab")
+
+# Lumped port + probe
+sim.add_port(
+    (0.006, 0.016, 0.016),
+    "ez",
+    impedance=50.0,
+    waveform=GaussianPulse(f0=5e9, bandwidth=0.8),
+)
+sim.add_probe((0.042, 0.016, 0.016), "ez")
+
+result = sim.run(num_periods=30)
+
+# S11
+s11_dB = 20 * np.log10(np.abs(result.s_params[0, 0, :]) + 1e-12)
+```
+
+## Patch Antenna with Non-Uniform Mesh
+
+```python
+from rfx import Simulation, Box, GaussianPulse, auto_configure
+import numpy as np
+
+# Auto-configure from geometry and frequency range
+geometry = [
+    (Box((0, 0, 0), (0.06, 0.06, 0.0016)), "fr4"),
+    (Box((0, 0, 0), (0.06, 0.06, 0)), "pec"),
+    (Box((0.015, 0.011, 0.0016), (0.0444, 0.049, 0.0016)), "pec"),
+]
+materials = {"fr4": {"eps_r": 4.4, "sigma": 0.025}, "pec": {"eps_r": 1.0, "sigma": 1e10}}
+config = auto_configure(geometry, (1e9, 4e9), materials=materials, accuracy="standard")
+print(config.summary())  # Shows dx, non-uniform dz, CPML, n_steps
+
+# Build simulation from auto-config
+sim = Simulation(**config.to_sim_kwargs())
+sim.add_material("fr4", eps_r=4.4, sigma=0.025)
+for shape, mat in geometry:
+    sim.add(shape, material=mat)
+sim.add_source((0.025, 0.03, 0.0008), "ez", waveform=GaussianPulse(f0=2.4e9))
+sim.add_probe((0.025, 0.03, 0.0008), "ez")
+
+result = sim.run(n_steps=config.n_steps)
+modes = result.find_resonances(freq_range=(1.5e9, 3.5e9))
+for m in modes:
+    print(f"f={m.freq/1e9:.4f} GHz, Q={m.Q:.0f}")
+```
+
+## Inverse Design
+
+```python
+from rfx import Simulation, Box, GaussianPulse
+from rfx.optimize import DesignRegion, optimize
+from rfx.optimize_objectives import minimize_s11
+
+sim = Simulation(freq_max=10e9, domain=(0.048, 0.032, 0.032), boundary="pec")
+sim.add_port((0.006, 0.016, 0.016), "ez", impedance=50.0,
+             waveform=GaussianPulse(f0=5e9, bandwidth=0.8))
+
+region = DesignRegion(
+    corner_lo=(0.016, 0.008, 0.008),
+    corner_hi=(0.032, 0.024, 0.024),
+    eps_range=(1.0, 4.4),
+)
+
+result = optimize(sim, region, minimize_s11, n_iters=40, lr=0.05)
+print(f"Final loss: {result.loss_history[-1]:.4f}")
+```
+
+## Key Features
+
+### Simulation Engine
+- 3D/2D Yee solver with CFS-CPML absorbing boundaries
+- True PEC mask (component-specific tangential zeroing)
+- Non-uniform z mesh for thin substrates
+- SBP-SAT subgridding research path
+- Periodic boundaries and oblique-incidence TFSF plane-wave source
+- Auto-configuration: `auto_configure()` derives dx, domain, CPML, timesteps, and source recommendation
+- Lumped RLC elements (series and parallel topologies)
+
+### Geometry
+- CSG primitives: Box, Sphere, Cylinder
+- CurvedPatch for staircase-approximated curved antenna layouts
+- Via for PCB through-hole / plated interconnect modeling
+
+### Sources & Ports
+- GaussianPulse, ModulatedGaussian, CW, custom waveforms
+- Soft sources and polarized sources
+- Lumped ports and multi-cell wire ports (conductor-to-conductor)
+- Waveguide ports with modal decomposition (eigenmode solver)
+- Polarized sources (Jones vector: circular, LHCP, slant45)
+
+### Materials
+- Dispersive: Debye, Lorentz/Drude
+- Magnetic (`mu_r` validated)
+- Thin conductors with subcell correction
+- Subpixel smoothing (Farjadpour/Kottke)
+- Built-in library: `pec`, `fr4`, `rogers4003c`, `copper`, `alumina`, `ptfe`, `water_20c`, and others
+
+### Analysis
+- S-parameters: lumped, wire (JIT-DFT), waveguide (N-port matrix)
+- Harminv resonance extraction (Matrix Pencil Method)
+- NTFF far-field, radiation patterns, RCS
+- Far-field polarization (axial ratio, tilt, sense)
+- Touchstone I/O, HDF5 checkpoints, VTK export
+- Time-domain field animation (MP4/GIF via `save_field_animation`)
+
+### Optimization
+- Design regions with `jax.grad` through full simulation
+- Adam optimizer, gradient checkpointing
+- Objective library: `minimize_s11`, `maximize_s21`, `target_impedance`, `maximize_bandwidth`, `maximize_directivity`
+
+## Benchmark Snapshot
+
+Core benchmark areas currently documented most strongly:
+
+| Geometry | rfx vs Meep | rfx vs OpenEMS | rfx vs Analytical |
+|----------|-------------|----------------|-------------------|
+| PEC cavity TM110 | 0.010% | **0.000%** | 0.013% |
+| FR4 cavity (eps=4.4) | 0.006% | — | 0.013% |
+| Rogers (eps=3.55) | 0.007% | — | 0.026% |
+| PTFE (eps=2.2) | 0.004% | — | 0.004% |
+| Alumina (eps=9.8) | 0.005% | — | 0.038% |
+
+Patch/microstrip resonance workflows are also active, but feed/port
+interpretation should be documented more carefully than the cavity/waveguide
+benchmarks.
+
+## GPU Performance (RTX 4090)
+
+| Grid | Steps | Time | Throughput |
+|------|-------|------|------------|
+| 23^3 | 200 | 0.087s | 28 Mcells/s |
+| 33^3 | 300 | 0.086s | 125 Mcells/s |
+| 43^3 | 400 | 0.103s | 310 Mcells/s |
+| 63^3 | 500 | 0.095s | 1,310 Mcells/s |
+
+Gradient (reverse-mode AD): ~0.31s for all grid sizes.
+
+## Documentation
+
+Full documentation: **[remilab.ai/rfx](https://remilab.ai/rfx/)** and
+repo-local guides under [`docs/guide/`](docs/guide/index.md).
+
+- [User Guide](https://remilab.ai/rfx/guide/) — Installation, API, materials, sources, probes
+- [AI Agent Guide](https://remilab.ai/rfx/agent/) — Auto-configuration, prompt templates, design workflows
+
+## Citation
+
+```bibtex
+@software{kim_rfx_2026,
+  author       = {Byungkwan Kim},
+  title        = {rfx: JAX-based differentiable 3D FDTD simulator},
+  institution  = {REMI Lab, Chungnam National University},
+  year         = {2026},
+  url          = {https://github.com/BK3536/rfx}
+}
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Acknowledgments
+
+Developed by [Byungkwan Kim](https://remilab.cnu.ac.kr) at the **Radar & ElectroMagnetic Intelligence (REMI) Laboratory**, Chungnam National University.
+
+AI-assisted development: Claude (Anthropic), Codex (OpenAI).