How flaport/sax works
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