# victorliu/s4 architecture

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

- Interactive diagram: https://gitdiagram.com/victorliu/s4
- Repository: https://github.com/victorliu/s4

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Numerical Back-Ends"
        EIGEN("(Eigen)"):::backend
        KISS("(kiss_fft)"):::backend
        FMM("(FMM)"):::backend
    end

    subgraph "Core Solver Library"
        CORE["C/C++ Core (S4)"]:::core
        S4R["C++ Interface (S4r)"]:::core
    end

    subgraph "Language Bindings & CLI"
        LUA["Lua Binding & CLI"]:::binding
        PY["Python Binding & CLI"]:::binding
        RBG["R Package (S4v2)"]:::binding
        MEX["MATLAB MEX Interface"]:::binding
    end

    subgraph "User Scripts/CLI"
        ULASCRIPT["Lua Scripts"]:::script
        PYSCRIPT["Python Scripts"]:::script
        RSCRIPT["R Scripts"]:::script
        MATSCRIPT["MATLAB Scripts"]:::script
    end

    subgraph "Build System"
        BS["Build System"]:::build
    end

    EXAMPLES["Examples"]:::examples
    TESTING["Testing"]:::examples
    DOC["Documentation"]:::doc

    ULASCRIPT -->|"Lua API"| LUA
    PYSCRIPT -->|"Python module"| PY
    RSCRIPT -->|"R API"| RBG
    MATSCRIPT -->|"MEX"| MEX

    LUA -->|"C API"| CORE
    PY -->|"C API"| CORE
    RBG -->|"C API"| CORE
    MEX -->|"C API"| CORE

    CORE -->|"matrix ops"| EIGEN
    CORE -->|"FFT"| KISS
    CORE -->|"FMM routines"| FMM
    S4R -->|"wraps Core"| CORE

    BS -->|make/CMake| CORE
    BS -->|make/CMake| S4R
    BS -->|make/CMake| LUA
    BS -->|make/CMake| PY
    BS -->|make/CMake| RBG
    BS -->|make/CMake| MEX
    BS -->|make/CMake| EXAMPLES
    BS -->|make/CMake| TESTING

    EXAMPLES -->|runs via| LUA
    EXAMPLES -->|runs via| PY
    EXAMPLES -->|runs via| RBG
    EXAMPLES -->|runs via| MEX

    TESTING -->|tests| LUA
    TESTING -->|tests| PY
    TESTING -->|tests| RBG
    TESTING -->|tests| MEX

    DOC -->|docs for| CORE
    DOC -->|docs for| S4R
    DOC -->|docs for| LUA
    DOC -->|docs for| PY
    DOC -->|docs for| RBG
    DOC -->|docs for| MEX
    DOC -->|docs for| EXAMPLES
    DOC -->|docs for| BS

    click CORE "https://github.com/victorliu/s4/tree/master/S4/"
    click S4R "https://github.com/victorliu/s4/tree/master/S4r/"
    click EIGEN "https://github.com/victorliu/s4/tree/master/Eigen/"
    click KISS "https://github.com/victorliu/s4/tree/master/S4/kiss_fft/"
    click FMM "https://github.com/victorliu/s4/tree/master/S4/fmm/"
    click LUA "https://github.com/victorliu/s4/blob/master/S4/ext_lua.c"
    click PY "https://github.com/victorliu/s4/blob/master/S4/main_python.c"
    click RBG "https://github.com/victorliu/s4/tree/master/ext/R/S4v2/"
    click MEX "https://github.com/victorliu/s4/tree/master/ext/matlab/"
    click BS "https://github.com/victorliu/s4/tree/master/Makefile"
    click EXAMPLES "https://github.com/victorliu/s4/tree/master/examples/"
    click TESTING "https://github.com/victorliu/s4/tree/master/testing/"
    click DOC "https://github.com/victorliu/s4/tree/master/doc/source/"

    classDef core fill:#ffdddd,stroke:#cc0000;
    classDef backend fill:#ddeeff,stroke:#0000cc;
    classDef binding fill:#ddffdd,stroke:#009900;
    classDef build fill:#eeeeee,stroke:#888888;
    classDef examples fill:#ffeedd,stroke:#ff6600;
    classDef doc fill:#f0ddff,stroke:#9900cc;
    classDef script fill:#ffffff,stroke:#666666,stroke-dasharray: 2 2;
```
