Fix wall_hit_cart/xend_cart inconsistency when from_cart fails

[krystophny]

Risk tier

• T0: docs, comments, small build metadata
• T1: pure refactor, no behavior change intended
• T2: local numerical logic
• T3: physics, output behavior, coordinate convention
• T4: parallelism, GPU, dependency, CI, or security-sensitive build logic

Correctness contract

Intended behavior change

For STL wall intersections, xend_cart is written from the authoritative CGAL wall_hit_cart point. If from_cart() fails in an ill-conditioned chartmap region, zend falls back to linearly interpolated reference coordinates for angle-space diagnostics.

Untraced particles now write zero xend_cart instead of reusing xstart_cart.

Behavior that must not change

Non-STL end positions still come from zend through the reference-coordinate Cartesian transform. zstart, zend, times_lost, class output, and wall-hit flags keep their existing shapes and meanings.

Coordinate / unit conventions

xend_cart and wall_hit_cart are Cartesian coordinates in the NetCDF xyz frame and units. zend remains phase-space output in reference coordinates.

Numerical invariants

For STL hits, xend_cart == wall_hit_cart at the recorded hit. For untraced particles, zend(1:3) == 0 implies xend_cart == 0.

Tests added

• unit: none
• integration: updated test_netcdf_results.py
• system: focused NetCDF output run through make test TEST=test_netcdf_results VERBOSE=1
• golden record: unchanged

Golden-record impact

• unchanged
• changed

Failure modes considered

• from_cart() may fail near ill-conditioned chartmap regions.
• Recomputing xend_cart from bad zend can move the displayed wall hit away from the true STL intersection.
• The short Python NetCDF fixture may not produce STL hits; the assertion is present and skips when no hit is generated.

Manual validation

The NetCDF focused test passed after updating the untraced-particle expectation and adding the wall-hit semantic assertion.

Verification

$HOME/code/prompts/scripts/check-writing-slop.py test/python/test_netcdf_results.py
PASS: no writing-slop candidates at threshold medium

make test TEST=test_netcdf_results VERBOSE=1
...
../../../test/python/test_netcdf_results.py::TestNetCDFResultsOutput::test_untraced_particles_have_zero_xend PASSED [ 75%]
../../../test/python/test_netcdf_results.py::TestNetCDFResultsOutput::test_wall_hits_use_authoritative_cartesian_hit SKIPPED [ 87%]
../../../test/python/test_netcdf_results.py::TestNetCDFResultsOutput::test_netcdf_has_proper_attributes PASSED [100%]
=================== 7 passed, 1 skipped in 77.71s (0:01:17) ====================
1/1 Test #88: test_netcdf_results ..............   Passed   78.21 sec
100% tests passed, 0 tests failed out of 1

[krystophny]

Visual Evidence

The histogram compares position differences between wall_hit_cart (true CGAL intersection) and xend_cart (computed from reference coordinates) before and after this fix.

Key improvements:

• Excellent agreement (<1 cm): 65.2% -> 78.6%
• Severe discrepancy (>500 cm): 22.3% -> 0%

Test configuration: SQUID stellarator, 1ms simulation, 1024 particles starting at s=0.6, using CGAL-embedded STL chartmap.

[qodo-code-review]

ⓘ Your approaching your monthly quota for Qodo. Upgrade your plan

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Supply chain integrity Description: The build fetches and builds a third-party dependency (CGAL) directly from a remote URL via FetchContent_Declare(URL ...) without any pinned integrity verification (e.g., URL_HASH/checksum or signature verification), which creates a software supply-chain risk if the downloaded archive is tampered with or replaced upstream. CMakeLists.txt [209-223] Referred Code include(FetchContent) FetchContent_Declare( cgal URL https://github.com/CGAL/cgal/releases/download/v6.0.1/CGAL-6.0.1.tar.xz DOWNLOAD_EXTRACT_TIMESTAMP TRUE ) FetchContent_GetProperties(cgal) if(NOT cgal_POPULATED) FetchContent_Populate(cgal) endif() # CGAL 6.x is header-only, just add include path set(CGAL_INCLUDE_DIR "${cgal_SOURCE_DIR}/include") message(STATUS "CGAL enabled via FetchContent: 6.0.1 (header-only)") message(STATUS "CGAL include dir: ${CGAL_INCLUDE_DIR}") add_compile_definitions(SIMPLE_ENABLE_CGAL)
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Fallback edge case: The new interpolation fallback silently does nothing when segment_length is zero, leaving z(1:3) potentially unupdated after from_cart() failure and risking the same inconsistency the fix aims to address. Referred Code segment_length = sqrt(sum((x_cur_m - x_prev_m)**2)) if (segment_length > 0.0_dp) then hit_distance = sqrt(sum((x_hit_m - x_prev_m)**2)) t_frac = hit_distance / segment_length u_ref_hit = u_ref_prev + t_frac * (u_ref_cur - u_ref_prev) call ref_to_integ(u_ref_hit, z(1:3)) end if Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[krystophny]

Update: The visual evidence histogram is available locally at /tmp/cgal_fix_comparison.png showing:

Position Discrepancy    Before Fix    After Fix
-------------------------------------------
< 1 cm (excellent)       65.2%         78.6%
> 100 cm (large)         32.1%          3.6%
> 500 cm (severe)        22.3%            0%

The fix significantly improves consistency between the CGAL-reported wall intersection (wall_hit_cart) and the position computed from reference coordinates (xend_cart).

[qodo-code-review]

ⓘ Your approaching your monthly quota for Qodo. Upgrade your plan

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Handle zero-length segment case Add an else branch to handle the zero-length segment case by setting u_ref_hit to u_ref_prev, resetting ierr_from_cart, and calling ref_to_integ to prevent an uninitialized state. src/simple_main.f90 [634-639] if (segment_length > 0.0_dp) then hit_distance = sqrt(sum((x_hit_m - x_prev_m)**2)) t_frac = hit_distance / segment_length u_ref_hit = u_ref_prev + t_frac * (u_ref_cur - u_ref_prev) + ierr_from_cart = 0 + call ref_to_integ(u_ref_hit, z(1:3)) +else + u_ref_hit = u_ref_prev + ierr_from_cart = 0 call ref_to_integ(u_ref_hit, z(1:3)) end if Apply / Chat Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a bug in the new fallback logic where a zero-length segment would leave the particle state un-updated and the error flag set, leading to incorrect behavior. The proposed fix is comprehensive and correct.	Medium
General	Clamp interpolation fraction Clamp the interpolation fraction t_frac to the [0, 1] range to guard against numerical errors and prevent extrapolation. src/simple_main.f90 [636] -t_frac = hit_distance / segment_length +t_frac = min(1.0_dp, max(0.0_dp, hit_distance / segment_length)) Apply / Chat Suggestion importance[1-10]: 6 __ Why: This suggestion correctly identifies a potential numerical instability where hit_distance could be slightly larger than segment_length, leading to extrapolation. Clamping t_frac makes the interpolation more robust against floating-point inaccuracies.	Low
Update