Touchstone RF & Signal Integrity (.sNp, .ts)

@modelscript/touchstone (languages/touchstone) provides high-performance zero-regex parsing, Vector Fitting rational macromodeling, Hamiltonian passivity enforcement, linear DAE lowering, and Modelica 3.x projection for Touchstone 1.0 & 2.0 multi-port RF, microwave, and high-speed digital interconnect decks.

---

Supported Extensions & Standards

Extension	Format	Description
.s1p	1-Port Network	Reflection coefficient ($S_{11}$) for antennas, terminations, and single-ended loads
.s2p	2-Port Network	Transmission ($S_{21},S_{12}$) and reflection ($S_{11},S_{22}$) for filters, amplifiers, transmission lines
.s3p, .s4p, .sNp	Multi-Port Network	Multi-pin connectors, differential transmission lines, crosstalk matrices
.ts	Touchstone 2.0	Advanced multi-port specification with mixed-mode S-parameters and per-port reference impedances

---

Key Capabilities

1. Multi-Format Parameter Formats

• Parses multi-port frequency grids with automatic unit conversion (Hz, kHz, MHz, GHz) and parameter types:
  • S-Parameters (Scattering matrix)
  • Y-Parameters (Admittance matrix)
  • Z-Parameters (Impedance matrix)
  • H / G Parameters (Hybrid matrices)
• Supports all standard data formats:
  • DB: Magnitude in decibels ($20{\log }_{10}|S|$), phase in degrees ($\mathrm{\angle }S$)
  • MA: Linear magnitude ($|S|$), phase in degrees ($\mathrm{\angle }S$)
  • RI: Real and imaginary components ($\text{Re}(S)+j\text{Im}(S)$)
• Enforces strict Touchstone matrix ordering conventions (e.g., $S_{21},S_{12}$ transpose ordering for 2-port networks).

2. Vector Fitting & Rational Macromodeling

• Converts discrete frequency-domain tabulated measurements into continuous-time rational transfer functions via Vector Fitting:$$S_{ij}(s)\approx \sum _{m=1}^P\frac{r_m}{s-p_m}+d+s\cdot e$$where $p_m$ are complex conjugate pole pairs in the open left half-plane ($\text{Re}(p_m)<0$), ensuring stability.
• Synthesizes a state-space realization:$$\dot{x}(t)=Ax(t)+Bu(t),y(t)=Cx(t)+Du(t)$$which lowers directly into ODE time-domain solvers without inverse FFT convolution lag.

3. Passivity Verification & Hamiltonian Matrix

• Verifies that the $N$-port network does not generate net energy across all frequencies:$$\parallel S(j\omega ){\parallel }_2\le 1\mathrm{\forall }\omega \in [0,\mathrm{\infty })$$
• Computes the eigenvalues of the Hamiltonian matrix:$$H=\left[\begin{array}{cc}A+B(I-D^{T}D{)}^{-1}{D}^{T}C& B(I-D^{T}D{)}^{-1}{B}^T\\ -C^T(I-D{D}^T{)}^{-1}C& -(A+B(I-D^{T}D{)}^{-1}{D}^{T}C{)}^T\end{array}\right]$$where purely imaginary eigenvalues identify exact passivity violation frequency crossover points.

4. Direct DAE Lowering & Modelica Projection

• Lowers state-space companion matrices directly into @modelscript/runtime's DAEBuilder SoA linear memory arena.
• Projects multiport networks into Modelica.Electrical.Analog pin networks for joint electro-mechanical and power electronic simulations (@modelscript/spice).

---

Pre-Flight Diagnostics

The Touchstone linter checks physical validity and numerical stability:

10 rules8 error2 warning Run with msx touchstone lint

Code	Rule	Severity	Message
M8301	passivity-violation	error	N-port scattering matrix violates passivity criterion (spectral norm <norm> > 1.0) at frequency <freq>.
M8302	causality-violation	error	Kramers-Kronig causality relation violated across frequency sweep: '<detail>'.
M8304	frequency-grid-non-monotonic	error	Frequency grid is not monotonically increasing: step from <prevFreq> to <currFreq> is non-increasing.
M8306	missing-option-line	warning	Missing '#' option line; defaulting to '# GHz S MA R 50'.
M8307	invalid-parameter-format	error	Invalid Touchstone parameter token or format '<token>'.
M8308	incomplete-matrix-data	error	Incomplete N-port matrix row: expected <expected> values, received <received>.
M8309	negative-reference-resistance	error	Reference resistance '<r>' must be strictly positive.
M8310	asymmetric-reciprocal-network	warning	Asymmetry in reciprocal S-parameter network: |S<i><j> - S<j><i>| = <diff> exceeds threshold.
M8311	no-frequency-points	error	Touchstone file contains no valid frequency parameter points.
M8312	duplicate-frequency-point	error	Duplicate frequency sample point '<freq>' encountered in sweep.

Generated from languages/touchstone/src/errors.ts. All languages →

---

CLI Usage

# Inspect Touchstone port count, frequency range, and impedance
msx touchstone inspect BandpassFilter.s2p

# Run pre-flight linting and validity checks
msx touchstone lint BandpassFilter.s2p

# Verify S-parameter passivity and compute maximum singular value
msx touchstone passivity BandpassFilter.s2p

# Fit rational state-space macromodel via Vector Fitting
msx touchstone fit BandpassFilter.s2p --order=6

# Lower state-space model to ModelScript linear DAE arena
msx touchstone to-dae BandpassFilter.s2p

# Project into Modelica 3.x electrical analog component
msx touchstone to-modelica BandpassFilter.s2p -o FilterModel.mo