fnec-rust

fnec-rust is a Rust-native antenna modeling workspace targeting near-100% practical compatibility with 4nec2, while keeping the codebase modular, testable, and portable.

Features

• Parse 4nec2 / NEC2 deck files (GW, GM, GR, GE, GN, EX, FR, RP, EN cards)
  • GM (Geometry Move): rotate and/or translate wire ranges in place, or append one transformed copy when tag_increment > 0
  • GR (Geometry Repeat): supported subset repeats existing wires by successive z-axis rotation
• Hallén MoM solver — physically accurate feedpoint impedance for thin-wire antennas
  • Validated: 51-segment λ/2 dipole at 14.2 MHz → 74.24 + j13.90 Ω (matches Python reference)
    • GN 1 (perfect ground at z=0) is supported via image method; dipole-ground-51seg regression is 81.91 + j16.42 Ω
    • GN types other than 1 are currently deferred; fnec warns and falls back to free-space behavior
    • GE ground-reflection flag: 1 = PEC image (handled); -1 = below-ground (warns); other values warn with valid range hint
    • Multi-wire Hallen: per-wire homogeneous constants and endpoint constraints; correct passive-wire (zero) RHS
• Segment current distribution table in CLI output (CURRENTS section after feedpoint table)
• RP radiation-pattern execution in CLI output (RADIATION_PATTERN section with theta/phi gain rows)
• Corpus validation can track and optionally gate external parity candidates (RP and impedance) recorded in corpus/reference-results.json
• Pulse-basis, continuity-basis, and sinusoidal-tapered Pocklington solvers (EXPERIMENTAL — known to diverge for thin wires)
  • sinusoidal now falls back to Hallen on single collinear chains when its residual budget is exceeded, so the CLI avoids returning misleading impedances for that path
• CLI binary fnec with selectable solver and RHS modes
• FR sweep support in CLI output and corpus validation gating
• Residual diagnostics printed to stderr on every run
• Modular crate workspace: parser, model, solver, accel, report, project, CLI, GUI, TUI

Quick start

cargo build --release
./target/release/fnec dipole.nec

Example deck (dipole.nec):

GW 1 51 0 0 -5.282 0 0 5.282 0.001
GE
EX 0 1 26 0 1.0 0.0
FR 0 1 0 0 14.2 0.0
EN

Example output (report contract v1):

FNEC FEEDPOINT REPORT
FORMAT_VERSION 1
FREQ_MHZ 14.200000
SOLVER_MODE hallen
PULSE_RHS Nec2

FEEDPOINTS
TAG SEG V_RE V_IM I_RE I_IM Z_RE Z_IM
1 26 1.000000 0.000000 0.013013 -0.002436 74.242874 13.899516

See docs/cli-guide.md for full option reference.

Support fnec-rust

If this project helps your work, please consider supporting ongoing development:

https://www.paypal.com/donate/?hosted_button_id=WY9U4MQ3ZAQWC

Goals

• Primary compatibility target: 4nec2 input and workflow expectations
• Secondary input dialect support: xnec2c where it provides real benefit
• Solver implemented from scratch in Rust
• CLI, GUI, and optional TUI frontends over a shared core
• Multithreaded CPU execution with staged GPU acceleration
• Explicit Linux-on-ARM targets: Raspberry Pi 4 (VideoCore VI GPU) and Raspberry Pi 5 (VideoCore VII GPU)

Workspace layout

crates/
	nec_parser/
	nec_model/
	nec_solver/
	nec_accel/
	nec_report/
	nec_project/
apps/
	nec-cli/
	nec-gui/
	nec-tui/
docs/

Contributor setup

Install the required cargo tools:

cargo install cargo-audit cargo-sbom

Install the local git hooks:

make install-hooks

This configures core.hooksPath to use .githooks/.

Local workflow checks

• Pre-commit: cargo fmt --all -- --check, cargo test --workspace
• Pre-push: cargo audit
• Docs validation: ./scripts/validate-docs-frontmatter.sh
• Remote ARM64 check (Pi over SSH): bash ./scripts/pi-remote-workspace-check.sh <user@host>
• Remote ARM64 benchmark CSV (Pi over SSH): bash ./scripts/pi-remote-benchmark.sh <user@host>
• Benchmark CSV delta view: bash ./scripts/pi-benchmark-compare.sh <base.csv> <candidate.csv>
• Benchmark CSV delta gate example: bash ./scripts/pi-benchmark-compare.sh --max-delta-pct 15 --fail-on-mode-drift <base.csv> <candidate.csv>

GitHub Actions includes benchmark-compare.yml, which runs on PRs and compares benchmarks/pi-base.csv vs benchmarks/pi-candidate.csv when both files exist. If either file is missing, the job reports a clean skip. When it runs, it also writes a benchmark delta preview to the Actions job summary.

Troubleshooting: Mobile approval dialogs

If you review or approve workflow/tool actions from a mobile device, some approval dialogs may be truncated, fail to render all options, or not submit reliably.

• Prefer desktop browser approval for multi-step actions (branch push, workflow changes, multi-file edits).
• If a mobile approval appears stuck, refresh and retry from desktop rather than re-running commands repeatedly.
• Keep command payloads and commit messages concise when you know approvals may be handled on mobile.

Version bump workflow

When bumping the workspace version:

1. Update Cargo.toml.
2. Regenerate the SPDX SBOM: cargo sbom --output-format spdx-json > SBOM.spdx.json
3. Update docs/changelog.md.
4. Update docs/releasenotes.md.
5. Update documentation references that include the new version.

Branch policy

main stays protected. Work happens on feature branches only, followed by pull requests.