---
title: Smith Lab
description: Guided 2D and 3D Smith Chart learning, RF measurement analysis, and deterministic impedance-matching design in WebGPU OS.
updated: 2026-07-15
---

# Smith Lab

Smith Lab is the `os.smith-lab` RF learning and design application. It combines
an accessible Smith Chart academy, deterministic matching-network synthesis,
bounded Touchstone import, and synchronized SVG and WebGPU visualizations. The
same frequency, load, reference impedance, selected marker, and sampled
component path drive every visible result. (Source:
`webgpu-os/factory/apps/smith-lab/RFPath.js`)

The opening surface uses an original generated scientific-cinematic coax and
reflection-field illustration. It is stored with its exact prompt and SHA-256
provenance and is explicitly labeled as a not-to-scale concept visualization.
It never supplies chart coordinates or calculation results; the SVG, WebGPU,
and RF model remain authoritative.

## Start here

The opening screen separates three jobs instead of exposing every RF control at
once:

- **Learn the chart** opens seven interactive lessons covering traveling waves,
  reflections, impedance, Smith mapping, components, stubs, and measurements.
- **Match an impedance** accepts ordinary `R + jX`, frequency, reference
  impedance, and velocity factor values, then synthesizes and ranks matching
  networks.
- **Open measurement data** accepts Touchstone files or pasted frequency tables
  and converts them to one canonical frequency-indexed dataset.

Guided mode uses plain-language prompts and staged decisions. Engineer mode
exposes overlays, exact numerical results, optimization, preferred-value
snapping, and tolerance controls. A metric can be selected to inspect its
symbolic formula, substitutions, assumptions, result, and units.

## Synchronized workbench

The central workbench provides an accessible SVG Smith Chart with impedance,
admittance, and combined grids. Its marker supports pointer dragging and arrow
keys. The selected point is synchronized with normalized impedance, admittance,
reflection coefficient, phase, VSWR, return loss, mismatch loss, reflected
power, voltage extrema, wavelength, and electrical length.

A circuit strip shows each proposed element in source-to-load order and its
value or electrical length. Selecting an element seeks the transformation
timeline to that exact operation. The chart draws each impedance, admittance,
or line segment separately, while the right panel shows the current substituted
state and the calculated terminal residual. The linked Cartesian plot evaluates
the selected network at every displayed frequency rather than repeating the
unmatched load. (Source: `webgpu-os/factory/apps/smith-lab/index.js`)

The path record stores the load, ordered transformation steps, exact sampled
impedance and admittance, normalized values, reflection coefficient, metrics,
formula, and terminal state. Lossless line samples preserve reflection
magnitude. Shunt-stub samples add the calculated branch susceptance in the
admittance domain. Exports include project JSON, chart SVG, 3D PNG, calculation
CSV, Touchstone 2.1, and a printable report.

## Physical and mathematical 3D

The physical RF view renders the current animated reflection coefficient as
separate incident, reflected, and total-voltage waves. It derives voltage and
current envelopes from the same complex reflection state, uses selected line
and stub electrical lengths, and adds energy-flow and voltage-stress cues.
Dragging changes orientation and the wheel changes zoom. Smith Lab creates the
WebGPU device and pipeline only when this view first opens, then retains that
runtime while the user switches views. A visible backend badge reports startup
and fallback state. The scene is explanatory rather than a validated
electromagnetic field solver. (Source:
`webgpu-os/factory/apps/smith-lab/SmithLab3D.js`)

Three mathematical views are separate from the engineering chart:

- **Calculated network path** lifts the exact per-element Smith trajectory into
  depth and colors impedance, admittance, and line operations separately.
- **Frequency tower** projects the evaluated sweep into a three-dimensional
  Smith trajectory and synchronizes its selected frequency marker.
- **Riemann view** maps the same calculated path onto the spherical complex
  plane as an optional lesson.

These mathematical views lazily create world-space triangle and line geometry,
then render it through the engine's WebGPU runtime with a perspective camera,
`depth24plus` depth testing, occlusion, orbit controls, and wheel zoom. Network
tubes are built from the exact per-element `RFPath` samples; frequency height
comes from the evaluated sweep; and the Riemann mesh uses stereographic mapping
of the calculated reflection coefficient. A painter-sorted Canvas perspective
renderer preserves the same geometry when WebGPU is unavailable. Reduced-motion
mode starts at a still frame while retaining direct manipulation. (Source:
`webgpu-os/factory/apps/smith-lab/SmithMath3DView.js`)

## RF calculation core

`RFMath.js` provides complex arithmetic, `Z ↔ Y ↔ Γ`, mismatch metrics,
lossless and lossy line transformations, lumped and distributed component
models, ABCD and S conversions, network cascading, parameter conversion, and
reference-impedance renormalization. `RFUnits.js` extends the existing safe
calculator parser; it does not use `eval`.

Accepted expressions include `1.085 GHz`, `36 - j74 ohm`,
`2*pi*1.085GHz*13.2nH`, `0.2195468 lambda`, `77 mm / 0.66`, and `-14 dB`.
Dimensional validation reports incompatible quantities rather than silently
coercing them.

Each primary conversion creates immutable ledger entries with a formula ID,
symbolic formula, substituted values, intermediate values, result, unit,
assumptions, and warnings. This deterministic ledger is the numerical authority
used by explanations and exports.

## Matching and tolerance automation

The solver enumerates both branches of two-element L networks, three-element π
and T candidates, open and short shunt stubs, and a quarter-wave transformer
when the load permits it. Candidates are evaluated through the common network
model, filtered for finite physical values, scored, and ranked.

Band optimization seeds bounded multi-start Nelder–Mead from synthesized
networks. It returns convergence evidence and the five best finite candidates.
Ranking modes favor best match, broadest band, simplicity, loss, or physical
size. E6 through E96 preferred-value snapping is available.

Tolerance analysis uses a fixed xorshift seed and 100–5,000 samples. The report
contains yield, minimum, median, 90th and 95th percentiles, worst case, and the
complete ordered envelope, so a run is reproducible from its project seed.

## Touchstone and datasets

`parseTouchstone(text, options)` accepts `.s1p`, `.s2p`, general `.sNp`, and
`.ts` sources. It supports RI, MA, and DB values; Hz, kHz, MHz, and GHz; S, Z,
Y, and two-port H/G parameters; full, lower, and upper matrices; two-port data
ordering; versioned keywords; comments; and per-port reference impedances.
Malformed or truncated input is rejected with diagnostics rather than repaired.

Imports are bounded to 16 ports, 250,000 frequency points, 2,000,000 complex
values, and 16 MiB of source text. A user selects the reflection port or
transmission pair used by the analysis. `serializeTouchstone()` emits a
Touchstone 2.1 full-matrix dataset while retaining source metadata in the Smith
Lab project.

The canonical `RfDataset` record contains frequencies, port count, parameter
kind, interleaved complex matrices, port references, source metadata, and parser
diagnostics. Manual points, pasted sweeps, analytical data, and imported
measurements use this same record.

## Public modules

| Interface | Purpose |
| --- | --- |
| `parseTouchstone()` / `serializeTouchstone()` | Bounded measurement interchange. |
| `createRfDataset()` / `analyzeRfDataset()` | Canonical RF records and synchronized metrics. |
| `convertNetworkParameter()` / `renormalizeNetwork()` | S/Z/Y conversion and port-reference changes. |
| `cascadeNetworks()` | Cascades ABCD records or aligned two-port datasets. |
| `solveMatchingProblem()` | Closed-form and deterministic topology enumeration. |
| `optimizeMatchingNetwork()` | Bounded multi-frequency candidate refinement. |
| `analyzeTolerance()` | Seeded tolerance yield and percentile evidence. |
| `buildCalculationLedger()` | Structured, exportable RF derivations. |
| `buildMatchingPath()` / `sampleMatchingPath()` | Exact per-element visual and explanatory RF states. |

The application itself retains the OS lifecycle contract:
`mount(root, syscalls)`, `unmount()`, and `getDebugSnapshot()`.

## Verification

The deterministic browser suite is `tests/smith-lab.html`. It covers Smith
boundaries, round-trip transformations, half-wavelength periodicity, unit
parsing, the corrected dual-stub fixture for `100 + j100 Ω` on `50 Ω`, stored
source-to-load stub topology, matching-path equivalence and line invariants,
Touchstone parsing and export, renormalization, matching synthesis, optimizer
determinism, tolerance reproducibility, responsive mounting, cleanup, and live
WGSL compilation. The application is also included in normal WebGPU OS app
discovery and release bundling.

## Engineering references

The line direction, constant-reflection-magnitude rotation, standing-wave
envelope, admittance-chart relationship, and shunt-stub construction follow the
[MIT 6.013 transmission-line treatment](https://web.mit.edu/6.013_book/www/chapter14/14.6.html).
The separation of incident and reflected traveling waves and the distributed
line model also follow the
[Keysight S-parameter design note](https://www.keysight.com/us/en/assets/7018-06743/application-notes/5952-1087.pdf).
These sources define the engineering behavior; all shipped prose, code, and
visual assets are original.