# flaport/sax architecture

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

- Interactive diagram: https://gitdiagram.com/flaport/sax
- Repository: https://github.com/flaport/sax

## Overview

##### Project type and purpose
- SAX is an open-source Python library/tool for S-parameter-based circuit simulation and optimization, built on top of JAX (autograd + XLA). It provides a thin functional wrapper around JAX to define component “models” (functions returning S-parameter dictionaries), assemble them into circuits (netlists), and run high-performance frequency-domain simulations.

##### File structure
Top‐level files and directories:
- sax/                ← core library package
– backends/         ← different solver backends (additive, klu, forward_only, etc.)
– circuit.py        ← netlist assembly and circuit builder
– netlist.py        ← internal netlist data structures & validation
– models.py         ← pre-defined component models (coupler, waveguide)
– multimode.py, loss.py, interpolation.py, utils.py, saxtypes.py
- docs/               ← Sphinx documentation sources
- examples/           ← Jupyter notebooks demonstrating library usage
- tests/              ← unit tests and notebook tests
- Dockerfile(.dev), Makefile, pyproject.toml, GitHub Actions workflows

##### Main components
A. User Layer
– “User Code” / Notebooks / Scripts
- Defines custom component functions or reuses sax.models
- Constructs a netlist dictionary and calls sax.circuit(...)
B. SAX Library Core
1. Circuit Builder (sax.circuit)
- Parses netlist “instances”, “connections”, “ports”
- Produces a composed model function
2. Netlist Engine (sax.netlist)
- Validates connectivity, builds internal graph of nodes & ports
3. Solver Backends (sax.backends)
- Implements S-parameter assembly & solution algorithms
- Additive, KLU, forward_only, etc.
4. Component Models (sax.models, multimode, loss)
- Pre-built building blocks (coupler, waveguide)
5. Utility Modules (interpolation, utils, saxtypes)
C. JAX Integration
– jax.numpy (jnp) for array ops
– jax.jit / XLA compiler for high-performance evaluation
– autograd for derivative-based optimization
D. Packaging & CI/CD
– pyproject.toml, Dockerfile, GitHub Actions (test, docs, release)
– Sphinx docs → HTML site
E. Testing & Examples
– tests/ suite for core functionality
– examples/ and internals/ notebooks for demonstration

##### Relationships and data flows
- User code → calls SAX API (sax.circuit, model functions)
- SAX circuit builder → uses netlist engine to assemble component graph
- Assembled function → executes with JAX, dispatches calls into solver backends
- Solver backends → compute S-parameter matrices, return dicts
- JAX autograd/XLA → transforms the composed function for speed and differentiation
- Results → returned to user code, plotted or optimized
- Docs generator and tests run separately via CI pipelines

##### Architectural patterns & design principles
- Functional, composition-based design: every circuit is just a Python function
- Plugin/backends pattern: interchangeable solver modules implementing a common interface
- Minimal data structures: uses standard Python dicts and tuples for S-parameters
- Separation of concerns: netlist parsing, circuit composition, numerical backends, and user interface are distinct layers

##### Technologies & frameworks
- Python ≥3.10
- JAX (jax, jax.numpy)
- Docker for containerized dev/test
- GitHub Actions for CI (testing, docs build, release)
- Sphinx (& Makefiles) for documentation
- pytest & nbval for tests

## Diagram (Mermaid)

```mermaid
graph TB
    %% User Layer
    subgraph "User Layer" 
        direction TB
        UserNotebooks["Example Notebooks"]:::user
        InternalNotebooks["Internal Notebooks"]:::user
    end

    %% SAX Core
    subgraph "SAX Library Core"
        direction TB
        CircuitBuilder["Circuit Builder\n(sax.circuit)"]:::core
        NetlistEngine["Netlist Engine\n(sax.netlist)"]:::core
        subgraph "Solver Backends"
            direction TB
            Additive["additive.py"]:::core
            Filipsson["filipsson_gunnar.py"]:::core
            ForwardOnly["forward_only.py"]:::core
            KLU["klu.py"]:::core
            BackendsInit["__init__.py"]:::core
        end
        subgraph "Component Models"
            direction TB
            Models["models.py"]:::core
            Multimode["multimode.py"]:::core
            Loss["loss.py"]:::core
        end
        subgraph "Utility Modules"
            direction TB
            Interpolation["interpolation.py"]:::core
            Utils["utils.py"]:::core
            Saxtypes["saxtypes.py"]:::core
        end
        EntryPoint["sax/__init__.py"]:::core
    end

    %% External Libraries
    subgraph "External Libraries" 
        direction TB
        JaxNum["jax.numpy"]:::external
        JaxJIT["jax.jit / XLA / autograd"]:::external
        PythonStd["Python stdlib"]:::external
    end

    %% CI/CD & Docs
    subgraph "CI/CD & Documentation"
        direction TB
        DocsSource["Sphinx Sources\n(docs/source/)"]:::infra
        Sphinx["Sphinx Build"]:::infra
        HTML["HTML Site"]:::infra
        TestsSuite["Testing Suite\n(tests/)"]:::infra
        GitHubActions["GitHub Actions"]:::infra
        PyProject["pyproject.toml"]:::infra
        DockerFiles["Dockerfile & Dockerfile.dev"]:::infra
        MakefileNode["Makefile"]:::infra
        Workflows[".github/workflows"]:::infra
    end

    %% Relationships - Runtime Flow
    UserNotebooks -->|"defines netlist & calls"| CircuitBuilder
    InternalNotebooks -->|"defines netlist & calls"| CircuitBuilder
    CircuitBuilder -->|"uses netlist engine"| NetlistEngine
    UserNotebooks -->|"uses models"| Models
    InternalNotebooks -->|"uses models"| Models
    CircuitBuilder -->|"composes function"| JaxJIT
    NetlistEngine -->|"validates & builds graph"| CircuitBuilder
    JaxJIT -->|"executes function"| Additive
    JaxJIT -->|"executes function"| Filipsson
    JaxJIT -->|"executes function"| ForwardOnly
    JaxJIT -->|"executes function"| KLU
    Additive -->|"returns S-parameter dict"| UserNotebooks
    Filipsson -->|"returns S-parameter dict"| UserNotebooks
    ForwardOnly -->|"returns S-parameter dict"| UserNotebooks
    KLU -->|"returns S-parameter dict"| UserNotebooks

    %% External dependencies
    CircuitBuilder -->|"calls"| JaxNum
    JaxJIT -->|"optimizes via"| XLA[("XLA Compiler")]:::external
    JaxJIT -->|"derivatives via"| Autograd[("Autograd")]:::external
    CircuitBuilder -->|"runs on"| PythonStd

    %% CI/CD & Docs Flow
    DocsSource -->|"RST input"| Sphinx
    Sphinx -->|"builds"| HTML
    GitHubActions -.->|"CI triggers"| TestsSuite
    GitHubActions -.->|"CI triggers"| Sphinx
    GitHubActions -.->|"CI triggers"| Release[("Release Pipeline")]:::infra

    %% Packaging files relationships
    GitHubActions --> PyProject
    GitHubActions --> DockerFiles
    GitHubActions --> MakefileNode
    GitHubActions --> Workflows

    %% Click Events
    click UserNotebooks "https://github.com/flaport/sax/tree/main/examples/"
    click InternalNotebooks "https://github.com/flaport/sax/tree/main/internals/"
    click CircuitBuilder "https://github.com/flaport/sax/blob/main/sax/circuit.py"
    click NetlistEngine "https://github.com/flaport/sax/blob/main/sax/netlist.py"
    click Additive "https://github.com/flaport/sax/blob/main/sax/backends/additive.py"
    click Filipsson "https://github.com/flaport/sax/blob/main/sax/backends/filipsson_gunnar.py"
    click ForwardOnly "https://github.com/flaport/sax/blob/main/sax/backends/forward_only.py"
    click KLU "https://github.com/flaport/sax/blob/main/sax/backends/klu.py"
    click BackendsInit "https://github.com/flaport/sax/blob/main/sax/backends/__init__.py"
    click Models "https://github.com/flaport/sax/blob/main/sax/models.py"
    click Multimode "https://github.com/flaport/sax/blob/main/sax/multimode.py"
    click Loss "https://github.com/flaport/sax/blob/main/sax/loss.py"
    click Interpolation "https://github.com/flaport/sax/blob/main/sax/interpolation.py"
    click Utils "https://github.com/flaport/sax/blob/main/sax/utils.py"
    click Saxtypes "https://github.com/flaport/sax/blob/main/sax/saxtypes.py"
    click EntryPoint "https://github.com/flaport/sax/blob/main/sax/__init__.py"
    click DocsSource "https://github.com/flaport/sax/tree/main/docs/source/"
    click TestsSuite "https://github.com/flaport/sax/tree/main/tests/"
    click PyProject "https://github.com/flaport/sax/blob/main/pyproject.toml"
    click DockerFiles "https://github.com/flaport/sax/tree/main/Dockerfile"
    click MakefileNode "https://github.com/flaport/sax/tree/main/Makefile"
    click Workflows "https://github.com/flaport/sax/tree/main/.github/workflows"

    %% Styling
    classDef user fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef core fill:#E6F4EA,stroke:#22863A,color:#22863A
    classDef external fill:#FFF5B1,stroke:#D29922,color:#D29922
    classDef infra fill:#F0F0F0,stroke:#6A737D,color:#6A737D
```
