fix: implement GE -1 zero-current ground mode and signed-mode validation - #134
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #133.
Summary
The
zero-currentground mode (NEC GE -1) was documented in the C API but effectively unimplemented:build_connections()guarded every plane check withignd > 0, so aGE -1geometry skipped the below-plane / in-plane rejections the NEC-2 Part 3 manual mandates, and aGE ±1with noGNcard silently simulated free space.This PR makes the code match the reported behavior:
nec_ground_connectionenum —NONE = 0,IMAGE = 1,ZERO_CURRENT = 2. The stable public value for zero-current remains2while the native geometry receives the signed NEC value-1(mapped in the C wrapper).GE -1keeps 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.GNcard now fails atsimulate()(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.necusedGE 1with noGNcard — gainedGN 1.testharness/python/test_examples.py::test_example1completed the geometry with flag1but no ground model (its own deck comment is plainGE) — now uses0.Everything else is behavior-preserving:
GE 0andGE 1outputs are byte-identical to master on all testharness decks (only the build-date header line differs).Verification
[ground]test cases:GE -1accepts 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, recordsground_connection() == -1);GNcard throws atxq_card(); withGN 1it simulates.example/test_nec.ccompiles clean and runs with the expected impedance values.