How victorliu/s4 works
Project Type and Purpose
• S4 is a scientific computing tool (open‐source solver) for electromagnetic fields in periodic, layered structures.
• Core is written in C/C++; it provides both a standalone API (S4 library) and language bindings (Lua, Python, R, MATLAB) plus command‐line front ends and example scripts.
• It relies on third‐party numerical libraries: Eigen for dense/sparse linear algebra, kiss_fft for FFT, custom FMM implementation under S4/fmm.
High‐Level Component Analysis
• Core Solver Library (directory “S4” and “S4r”): C/C++ implementation of the physics engine, eigenvalue solvers, field interpolation, special functions, FMM.
• Numerical Back‐Ends:
• Eigen (third‐party) – dense/sparse matrix support, linear algebra decomposition and iterative solvers.
• kiss_fft – FFT routines used by FMM routines.
• FMM (Fast Multipole Method) – in S4/fmm, uses kiss_fft interface.
• Language Bindings & Front Ends:
• Lua: ext_lua.c + main_lua.c + modules/*.lua and C modules for sampling.
• Python: main_python.c + modules setup.py + .py wrappers.
• R: ext/R/S4v2 package code.
• MATLAB: ext/matlab/S4mex.c + .m interface classes.
• Build System:
• Makefiles at top-level (Makefile, Makefile.common, platform‐specific).
• CMakeLists in Eigen/src and optionally for building third‐party.
• gensetup.py.sh orchestrates configuration.
• Examples & Testing:
• examples/ – sample scripts per dimension, C API, MPI demos.
• testing/ – automated tests and scripts.
• Documentation:
• doc/source, doc/build – Sphinx‐generated HTML and Markdown manual.
• doc/Capi.md – C API reference.
Relationships & Interactions
• User → Script (Lua/Python/R/MATLAB) → Language Binding → Core Solver API → Numerical Libraries (Eigen, kiss_fft, FMM).
• Core Solver exports a C API, consumed either by CLI front ends (main_lua, main_python) or by language extension modules.
• Build system → compiles Eigen (headers only), core library, binding modules, example binaries, and test executables.
• Testing harness and examples invoke the frontend executables or modules to validate functionality.
Architectural Patterns & Design Principles
• Plugin/Modular Architecture: language support via shared‐object modules (.so/.dll) or MEX files.
• Layered Separation:
• Layer 1: Numerical kernels (Eigen, FFT).
• Layer 2: Core physics library (S4 C/C++), FMM, sampling utilities.
• Layer 3: Bindings & front ends (interpreters, CLI, scripts).
• Layer 4: User‐level examples, tests, documentation.
• Single core code‐base reused across multiple language environments.