Skip to content

fix: implement GE -1 zero-current ground mode and signed-mode validation - #134

Merged
tmolteno merged 2 commits into
masterfrom
fix/zero-current-ground-mode
Sep 1, 2026
Merged

tmolteno merged 2 commits into
masterfrom
fix/zero-current-ground-mode

Conversation

@tmolteno

@tmolteno tmolteno commented Sep 1, 2026

Copy link
Copy Markdown
Owner

Closes #133.

Summary

The zero-current ground mode (NEC GE -1) was documented in the C API but effectively unimplemented: build_connections() guarded every plane check with ignd > 0, so a GE -1 geometry skipped the below-plane / in-plane rejections the NEC-2 Part 3 manual mandates, and a GE ±1 with no GN card silently simulated free space.

This PR makes the code match the reported behavior:

  • Public ABI: new nec_ground_connection enum — NONE = 0, IMAGE = 1, ZERO_CURRENT = 2. The stable public value for zero-current remains 2 while the native geometry receives the signed NEC value -1 (mapped in the C wrapper).
  • Validation: both signed ground modes now reject segments that extend below the ground plane or lie in it; segments may still end on the plane. GE -1 keeps the Fortran connection semantics — a ground-touching end stays a free end, so the current goes to zero there — and the low-horizontal-wire escape hatch (height < 1e-3 × segment length) still applies, so only a segment with both ends exactly on the plane is rejected as lying in it.
  • Ground model required: a non-none connection without a GN card now fails at simulate() (NEC-2 Part 3: "A positive or negative value of I1 does not cause a ground to be included in the calculation... The ground parameters must be specified on a program control card following the geometry cards.") instead of silently running free space.

Behavior changes for existing inputs

  • testharness/data/discone.nec used GE 1 with no GN card — gained GN 1.
  • testharness/python/test_examples.py::test_example1 completed the geometry with flag 1 but no ground model (its own deck comment is plain GE) — now uses 0.

Everything else is behavior-preserving: GE 0 and GE 1 outputs are byte-identical to master on all testharness decks (only the build-date header line differs).

Verification

  • Unit suite: 708 assertions in 79 test cases, all pass, including 7 new [ground] test cases:
    • both signed modes reject below-plane and in-plane segments;
    • GE -1 accepts a segment ending on the plane and a low horizontal wire;
    • nec_geometry_complete(nec, 2) maps to native -1 (rejects a below-plane segment, records ground_connection() == -1);
    • ground connection without a GN card throws at xq_card(); with GN 1 it simulates.
  • All 41 runnable testharness decks produce output identical to master (the 11 that fail on master fail identically here — pre-existing overlap-check failures, unrelated to this change).
  • example/test_nec.c compiles clean and runs with the expected impedance values.

The zero-current ground mode (NEC GE -1) was documented but effectively
treated as no ground: build_connections() guarded every plane check with
ignd > 0, so below-plane and in-plane segments were silently accepted
and no ground model was required. Per NEC-2 Part 3, when I1 is nonzero
no segment may extend below the ground plane or lie in it, and the
ground parameters must be specified on a GN card.

- Add nec_ground_connection to the C API: ZERO_CURRENT stays the stable
  public ABI value 2 while the native geometry receives -1.
- Validate both signed ground modes in build_connections(); GE -1 keeps
  the Fortran connection semantics (a ground-touching end stays a free
  end, so current goes to zero there) and the low-horizontal-wire escape
  hatch (only a segment with both ends exactly on the plane is rejected
  as lying in it).
- Fail at simulate() when a non-none connection has no ground model
  instead of silently running free space.
- discone.nec gains the missing GN 1; test_example1 completes the
  geometry with 0, matching its free-space deck.
- Unit tests cover the plane checks for both signed modes, the ABI
  mapping, and the ground-model requirement (closes #133).
The zero-current fix makes a non-none ground connection without a GN card
fail at simulate(), so test_example1 (a free-space dipole whose deck
comment shows plain "GE") must complete the geometry with flag 0. Add a
comment so the change is not mistaken for a typo.
@tmolteno
tmolteno merged commit 9b6d00d into master Sep 1, 2026
4 checks passed
@tmolteno
tmolteno deleted the fix/zero-current-ground-mode branch September 1, 2026 03:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

GE -1 (zero-current) ground mode is unimplemented; signed ground modes lack validation

1 participant