# Antenna Simu Web

Web app for designing antennas and tuning their parameters: analytical calculators now,
radiation-pattern visualization and full-wave simulation (NEC-2 via WebAssembly) planned.
Pure HTML/JS/CSS, no build step, no server required.

Fork of [9M2PJU Basic Antenna Calculator](https://github.com/9M2PJU/9M2PJU-Basic-Antenna-Calculator)
by 9M2PJU. Main changes from upstream: the monolithic `script.js` was split into ES modules
(calculation core, tool descriptors and UI are separate layers) and a Node-based test suite
was added. All upstream calculators and the PWA behavior are preserved.

## Features

- Wire antennas: dipole, inverted V, OCF dipole, EFHW, folded dipole, fan dipole element, random wire, doublet/Zepp, G5RV/ZS6BKW reference, T2FD and Beverage receive antenna.
- Verticals: quarter-wave ground plane, 5/8-wave vertical, half-wave vertical, discone, J-Pole and Slim Jim.
- Beams: 3-element Yagi, Moxon, HB9CV, turnstile/crossed dipole and 2-element quad.
- Loops: full-wave loop, delta loop, small magnetic loop geometry, halo/squalo and eggbeater.
- Matching tools: L-network designer (both topologies with component values), impedance ratio, common balun/unun ratios, quarter-wave transformer and coax choke length helper.
- Feedline and stubs: coax input impedance / SWR / loss on a lossy line, coax electrical lengths, balanced line designer, open stubs, shorted stubs and SWR mismatch loss.
- Dipole feedpoint impedance by the induced-EMF method (Balanis ch. 8) with an SWR-vs-frequency chart and resonance readout.
- Full-wave simulation: a built-in thin-wire Method of Moments solver (rooftop basis, Galerkin testing, free space) runs in a Web Worker for dipole, inverted V, 3-element Yagi, Moxon, 2-element quad and full-wave/delta loops — simulated feedpoint impedance, SWR sweep, gain, front-to-back and true 2D/3D patterns solved from the actual wire currents.
- Metric/imperial output, amateur-band detection, material velocity factor, coax velocity factor and saved preferences.
- PWA support with install prompt, offline cache, old-cache cleanup and navigation fallback.

## Running

ES modules, `manifest.json` and the service worker do not load from `file://`
(the browser treats every `file:` URL as a unique origin), so the folder must be
served over HTTP. Any of these works:

- double-click `start.cmd` (Windows: starts a server and opens the browser), or
- `python -m http.server 8000` / `npm run serve`, then open `http://localhost:8000`, or
- the VS Code "Live Server" extension on `index.html`.

On localhost the service worker is intentionally not registered, so edits show up
on plain reload. Open `http://localhost:8000/?sw=1` to test PWA/offline behavior.

## Testing

Requires Node 18+; no dependencies to install:

```bash
npm test
```

The suite checks the unit-conversion helpers, reference dimensions for known antennas
(half-wave dipole, quarter-wave ground plane, quarter-wave transformer, SWR/mismatch,
open-wire line impedance), smoke-tests every registered tool across the HF-UHF range,
and validates the radiation-pattern engine against Balanis reference values
(half-wave dipole 2.15 dBi / 78°, quarter-wave monopole 5.16 dBi / 39°, full-wave
dipole 3.8 dBi, array-factor broadside/endfire/cardioid cases).

## Structure

```text
index.html            Application markup
styles.css            Responsive desktop/mobile styling
src/main.js           Entry point
src/core/             Calculation core: constants, units, context, complex math, tool registry
src/physics/          Analytical models (Balanis): far-field patterns, directivity/HPBW metrics,
                      Si/Ci integrals, induced-EMF dipole impedance, lossy-line and L-network math,
                      and the thin-wire MoM solver (mom.js)
src/sim/              Web Worker wrapper for the MoM solver
src/tools/            Tool descriptors by category (wire, vertical, beam, loop, matching, feedline)
src/ui/               DOM rendering, state, PWA install logic, SVG diagrams
src/viz/              Plotly plots: polar E/H-plane cuts, 3D pattern surface, SWR-vs-frequency chart (lazy-loaded)
vendor/katex/         Vendored KaTeX for formula rendering (kept local for PWA offline)
vendor/plotly/        Vendored Plotly.js for pattern plots (lazy-loaded on first use)
tests/                node --test suite
manifest.json         PWA manifest
sw.js                 Service worker and offline cache
```

Each tool is a descriptor object (`id`, `title`, `calculate(context)` and friends) registered
in `src/core/registry.js`. Later stages will extend descriptors with radiation patterns
(`pattern`), KaTeX formulas (`formulaTex`) and NEC-2 geometry (`necGeometry`) without
changing the UI layer. See the descriptor contract in `src/core/registry.js`.

## Calculation Notes

The app gives practical starting dimensions, not guaranteed final build dimensions. Antenna
resonance and impedance depend on height, ground, wire diameter, nearby objects, feedline,
construction style and weatherproofing.

For transmit antennas, start slightly long, install the antenna in its final position, then
trim or adjust while measuring with an antenna analyzer or SWR meter.

## License

GPL-3.0-or-later, inherited from the upstream project (see `LICENSE`). Upstream's README
stated "MIT", but the repository's LICENSE file is and was GPL-3.0, which governs.