Refactor

[krystophny]

PR Type

Enhancement, Tests, Bug fix, Documentation

---

Description

• Major refactoring to support field-agnostic canonical coordinate computation - Added new modules and interfaces to work with different magnetic field types (VMEC, GVEC) through unified APIs
• Added comprehensive GVEC field support - New VMEC field adapter for GVEC compatibility, field evaluation modules, and coordinate transformation fixes
• Introduced optional GVEC compilation - Made GVEC support conditional with ENABLE_GVEC option and proper conditional compilation guards
• Enhanced testing infrastructure - Added multi-file golden record comparison, granular test targets (fast/slow/regression), and comprehensive test suites for new functionality
• Restructured CI workflow - Separate jobs for different test types with conditional execution based on PR draft status
• Added new mathematical modules - 3D spline interpolation, field-agnostic Newton iteration, and Boozer coordinate conversion
• Centralized external library interfaces - New modules for MINPACK, LAPACK, and sorting routine interfaces
• Bug fixes - Fixed integer conversion issues in grid sampling and coordinate transformation signs in GVEC fields
• Code cleanup - Removed unused variables and imports, improved formatting and documentation
• Enhanced build system - Updated CMake configuration with better dependency management and debug flags
• Improved documentation - Added classification example docs, updated testing guides, and Python wrapper installation instructions

---

Changes walkthrough 📝

	Relevant files
Enhancement	7 files get_canonical_coordinates.f90 Field-agnostic canonical coordinates refactoring                  src/get_canonical_coordinates.f90 • Refactored code to support field-agnostic canonical coordinate computation • Added new subroutines get_canonical_coordinates_with_field and get_canonical_coordinates_impl • Introduced module variable current_field for field storage and thread-private access • Updated rhs_cancoord to use field-agnostic Newton solver and field evaluation +1075/-1018 field_can.f90 Field-agnostic initialization updates                                        src/field_can.f90 • Updated init_field_can to use field-agnostic coordinate computation functions • Added proper field allocation and deallocation for memory management • Modified function calls to use _with_field variants +10/-4    vmec_field_adapter.f90 Add VMEC field adapter for GVEC compatibility                        src/field/vmec_field_adapter.f90 • Creates a new adapter module to provide VMEC-compatible interface for GVEC fields • Implements field evaluation, iota interpolation, lambda interpolation, and data interpolation functions • Uses numerical differentiation for vector potential derivatives in GVEC fields • Provides both legacy and field-object-based interfaces for compatibility +295/-0  vmec_field_eval.f90 Extract VMEC field evaluation to separate module                  src/field/vmec_field_eval.f90 • Extracts VMEC-only field evaluation functions from adapter module • Provides field evaluation, iota interpolation, lambda interpolation functions • Always available regardless of GVEC support compilation • Maintains backward compatibility with existing VMEC interfaces +163/-0  boozer_converter.f90 Add field-agnostic Boozer coordinate conversion                    src/boozer_converter.f90 • Adds field-agnostic version of Boozer coordinate conversion • Implements get_boozer_coordinates_with_field accepting MagneticField objects • Maintains backward compatibility with original VMEC-only interface • Uses conditional compilation for GVEC support +67/-4    spline_3d_interpolation.f90 Add shared 3D spline interpolation module                                src/spline_3d_interpolation.f90 • Shared 3D spline interpolation module for canonical and Boozer coordinates • Implements tensor product spline evaluation using nested Horner's method • Provides both single quantity and vector quantity evaluation functions • Optimized for efficient evaluation of multiple physical quantities +103/-0  field_newton.f90 Add field-agnostic Newton iteration module                              src/field/field_newton.f90 • Field-agnostic Newton iteration module for coordinate transformations • Implements Newton solver to find field-specific theta from canonical theta • Abstracts stream function evaluation for different field types • Provides convergence checking and iteration counting +103/-0
Tests	16 files test_vmec_gvec.f90 Test optimization and formatting improvements                        test/tests/test_vmec_gvec.f90 • Reduced multharm parameter from 5 to 3 for faster testing • Minor formatting improvements with consistent spacing +5/-251  fort.10022 New test output file                                                                          test/golden_record_sanity/matching/classifier_fast/fort.10022 • Added new test output file containing single value "1.1" +1/-0      test_vmec_gvec_adapter.f90 Add comprehensive VMEC vs GVEC adapter comparison test      test/tests/test_vmec_gvec_adapter.f90 • Comprehensive test comparing VMEC and GVEC field adapter outputs • Tests field evaluation, lambda interpolation, and iota interpolation consistency • Includes detailed diagnostics for different quantity types and tolerances • Provides status reporting on essential vs computed quantities +284/-0  test_adapter_consistency.f90 Add adapter consistency test for field interfaces                test/tests/test_adapter_consistency.f90 • Tests consistency between direct VMEC calls and field object calls • Validates GVEC field results for essential quantities like sqrt(g) and iota • Checks vector potential derivatives and magnetic field components • Focuses on GVEC field adapter functionality validation +181/-0  test_canonical_gvec.f90 Add canonical coordinates integration test for GVEC            test/tests/test_canonical_gvec.f90 • Integration test for canonical coordinates with GVEC fields • Tests adapter functions for field evaluation, lambda interpolation, iota interpolation • Validates consistency between different adapter interfaces • Checks that essential quantities are computed correctly +175/-0  test_spline_3d.f90 Add 3D spline interpolation unit tests                                      test/tests/test_spline_3d.f90 • Unit test for 3D spline interpolation module functionality • Tests single quantity and vector quantity evaluation • Includes consistency checks and stress testing with multiple points • Validates edge cases and boundary conditions +166/-0  test_simple_vmec_gvec.f90 Add SIMPLE integration test for VMEC vs GVEC                          test/tests/test_simple_vmec_gvec.f90 • Comprehensive test running SIMPLE with both VMEC and GVEC fields • Compares particle confinement statistics between field types • Creates separate namelists for VMEC and GVEC configurations • Validates that results are consistent within tolerance +144/-0  compare_golden_results.sh Add multi-file comparison for classifier test case              test/golden_record/compare_golden_results.sh • Adds multi-file comparison support for classifier_fast test case • Implements comparison of multiple output files beyond just times_lost.dat • Uses new compare_files_multi.py script for comprehensive validation • Maintains backward compatibility for single-file test cases +41/-23  fort.10000 Add reference data for classifier fast test                            test/golden_record_sanity/matching/classifier_fast/fort.10000 • Adds reference data file for classifier fast test case validation • Contains numerical values for golden record comparison +3/-0      compare_files_multi.py Add multi-file comparison utility for golden record testing test/golden_record/compare_files_multi.py • New Python script for comparing multiple files between directories • Supports both numerical and binary file comparison methods • Includes command-line interface with JSON output option • Provides detailed comparison results and summary statistics +204/-0  golden_record_multi.sh Add multi-version golden record comparison script                test/golden_record/golden_record_multi.sh • New shell script for comparing working copy against multiple reference versions • Runs working copy tests once and compares against all reference versions • Supports expected failure flags for specific reference versions • Includes comprehensive error handling and status reporting +200/-0  test_golden_record_sanity.sh Add comprehensive golden record sanity test suite                test/golden_record_sanity/test_golden_record_sanity.sh • Comprehensive test suite for validating golden record comparison system • Tests both matching and non-matching scenarios across multiple test cases • Includes colored output and detailed test result reporting • Validates both individual file and full comparison workflows +169/-0  test_golden_record_sanity_simple.sh Add simplified golden record sanity test script                    test/golden_record_sanity/test_golden_record_sanity_simple.sh • Simplified version of golden record sanity tests • Tests single file, multi-file, and full comparison scenarios • Provides basic validation of comparison system functionality +82/-0    CMakeLists.txt Refactor test configuration with conditional GVEC support test/tests/CMakeLists.txt • Conditionally enable GVEC-related tests based on ENABLE_GVEC option • Replace individual golden record tests with efficient multi-version test • Add golden record sanity test to validate comparison system • Add new test executable for 3D spline functionality +76/-40  simple.in Add fast classifier test configuration                                      test/golden_record/classifier_fast/simple.in • New test configuration with minimal particle count (32) • Enables fast classification mode and deterministic behavior • Configured for quick golden record testing +15/-0    simple.in Add classifier test configuration                                                test/golden_record/classifier/simple.in • New test configuration for classifier testing • Uses minimal particle count and deterministic settings • Configured for golden record comparison testing +11/-0
Dependencies	8 files orbit_symplectic_quasi.f90 Added minpack interface import                                                      src/orbit_symplectic_quasi.f90 • Added import for hybrd1 from minpack_interfaces module +1/-5      minpack_interfaces.f90 Add MINPACK library interfaces for optimization routines  src/contrib/minpack_interfaces.f90 • Adds Fortran interfaces for MINPACK optimization library routines • Includes interfaces for nonlinear equation solvers and least squares fitting • Provides function signatures for enorm, dogleg, fdjac1, hybrd, lmder, etc. +155/-0  orbit_symplectic.f90 Update LAPACK interface import in symplectic orbit              src/orbit_symplectic.f90 • Adds import for dgesv LAPACK routine from new interfaces module • Updates dependency to use centralized LAPACK interface definitions +1/-0      lapack_interfaces.f90 Add LAPACK interfaces module                                                          src/lapack_interfaces.f90 • Provides Fortran interface for LAPACK dgesv linear system solver • Centralizes LAPACK routine interfaces for consistent usage • Defines proper parameter types and intent specifications +13/-0    check_orbit_type.f90 Update sorting interface import in orbit type check            src/check_orbit_type.f90 • Adds import for sortin sorting routine from new sorting module • Updates dependency to use centralized sorting interface +1/-0      sorting_mod.f90 Add sorting module interfaces                                                        src/sorting_mod.f90 • Provides Fortran interface for sortin sorting routine • Centralizes sorting routine interfaces for consistent usage • Defines proper parameter types and intent specifications +12/-0    test_magfie.f90 Update LAPACK interface import in magnetic field test        test/tests/test_magfie.f90 • Adds import for dgesv LAPACK routine from interfaces module • Updates dependency to use centralized LAPACK interface definitions +1/-0      pyproject.toml Update f90wrap dependency source                                                  pyproject.toml • Update f90wrap dependency to use specific Git repository • Ensures compatibility with latest f90wrap version +1/-1
Bug fix	2 files field_gvec.f90 Fix GVEC field coordinate transformations and exports        src/field/field_gvec.f90 • Removes convert_vmec_to_gvec function from public exports • Fixes coordinate transformation signs for phi = -zeta mapping • Corrects contravariant magnetic field component calculations • Updates vector potential component transformations +18/-44  samplers.f90 Fix integer conversion in grid sampling                                    src/samplers.f90 • Fixes integer conversion issues in sample_grid function • Converts xsize and ngrid from real to integer types properly • Ensures proper array indexing and loop bounds • Maintains grid sampling functionality with correct data types +15/-14
Configuration changes	12 files export_field_2d.f90 Add conditional compilation for GVEC in field export          test/tests/export_field_2d.f90 • Adds conditional compilation guards for GVEC-specific code • Maintains VMEC field export functionality when GVEC unavailable • Uses #ifdef GVEC_AVAILABLE preprocessor directives • Ensures compilation compatibility across different build configurations +36/-4    field.f90 Add conditional GVEC support in field module                          src/field.f90 • Adds conditional compilation for GVEC field support • Uses #ifdef GVEC_AVAILABLE to guard GVEC-specific imports and code • Provides error message when GVEC files encountered without GVEC support • Maintains backward compatibility for VMEC and coils fields +7/-0      test_vmec.py Reduce harmonic resolution in VMEC Python test                      test/python/test_vmec.py • Reduces multharm parameter from 7 to 3 for faster test execution • Maintains VMEC Python test functionality with lower harmonic resolution +1/-1      main.yml Restructure CI workflow with conditional test execution    .github/workflows/main.yml • Complete workflow restructure with separate jobs for different test types • Add conditional test execution based on PR draft status • Separate fast/slow tests from regression tests with different triggers • Add documentation build job with LaTeX and LyX support +118/-16 Makefile Enhance Makefile with granular test targets                            Makefile • Add multiple test targets: test-fast, test-slow, test-regression, test-all • Implement test filtering using CTest labels • Improve test command structure with common CTEST_CMD variable +24/-8    CMakeLists.txt Make GVEC support optional and improve build configuration CMakeLists.txt • Make GVEC support optional with ENABLE_GVEC option (default OFF) • Conditionally fetch and configure GVEC library only when enabled • Add debug compilation flags and remove interprocedural optimization +18/-14  CMakeLists.txt Update source configuration with conditional GVEC support src/CMakeLists.txt • Add new source files for LAPACK interfaces, sorting, and spline interpolation • Conditionally include GVEC-specific sources based on ENABLE_GVEC option • Update library linking to conditionally include GVEC dependencies +23/-6    simple.in Update classification example with reduced particle count examples/classification/simple.in • Reduce test particle count from 65536 to 5000 • Change VMEC file from QH to QA reactor scale configuration • Add deterministic = .True. parameter for reproducible results +3/-2      .pre-commit-config.yaml Add pre-commit configuration for code quality                        .pre-commit-config.yaml • New pre-commit configuration with code quality hooks • Includes trailing whitespace, file format, and security checks • Adds custom hook to run fast tests before commits +30/-0    settings.json Add VS Code Fortran formatting configuration                          .vscode/settings.json • New VS Code configuration for Fortran formatting • Configures fprettify formatter with specific style settings • Sets indentation, whitespace, and case formatting rules +19/-0    CMakeLists.txt Update contrib build with MINPACK interfaces                          src/contrib/CMakeLists.txt • Add new minpack_interfaces.f90 source file • Disable specific compiler warnings for legacy minpack.f90 code +6/-2      .fprettify Add fprettify formatter configuration                                        .fprettify • New configuration file for fprettify Fortran formatter • Sets indentation, line length, and whitespace formatting rules +10/-0
Formatting	3 files test_poincare1.f90 Remove unused variables in Poincare test                                  test/tests/test_poincare1.f90 • Removes unused variable declarations (e_mass, snear_axis, etc.) • Cleans up variable definitions that were declared but never used • Maintains core Poincare test functionality • Improves code clarity by removing dead code +7/-14    test_coord_trans.f90 Remove unused import in coordinate transformation test      test/tests/test_coord_trans.f90 • Removes unused import of e_mass from util module • Cleans up import statement to only include used variables • Maintains coordinate transformation test functionality +1/-6      test_collis.f90 Remove unused import in collision test                                      src/test_collis.f90 • Removes unused import of e_mass from util module • Cleans up import statement to only include used variables • Maintains collision test functionality +1/-1
Documentation	4 files cut_detector.f90 Add safety comment for array bounds                                            src/cut_detector.f90 • Adds safety comment about array bounds in orbit stencil code • Documents that array access is safe due to loop condition check • No functional changes, only documentation improvement +1/-0      README.md Add classification example documentation                                  examples/classification/README.md • New documentation explaining class_parts.dat file column meanings • Describes classification types and optimization workflow • Provides recipe for orbit classification optimization process +26/-0    CLAUDE.md Update Claude documentation with new test targets                CLAUDE.md • Update testing documentation with new granular test targets • Document verbose output behavior and single test execution • Clarify test system development status +5/-1      README.md Add Python wrapper installation documentation                        README.md • Add Python wrapper installation instructions • Include f90wrap dependency and installation commands +6/-0
Additional files	35 files TODO.md +0/-194  spline_vmec_data.f90 +0/-3      fort.20000 +1/-0      fort.40022 +1/-0      fort.40032 +1/-0      fort.50022 +1/-0      fort.50032 +1/-0      simple.in +1/-0      simple.in +1/-0      fort.10000 +3/-0      fort.10022 +1/-0      fort.20000 +1/-0      fort.40022 +1/-0      fort.40032 +1/-0      fort.50022 +1/-0      fort.50032 +1/-0      simple.in +1/-0      simple.in +1/-0      fort.10000 +3/-0      fort.10022 +1/-0      fort.20000 +1/-0      fort.40022 +1/-0      fort.40032 +1/-0      fort.50022 +1/-0      fort.50032 +1/-0      simple.in +1/-0      simple.in +1/-0      create_1d_radial_plots.py +0/-295  detailed_field_analysis.py +0/-419  investigate_field_differences.py +0/-497  plot_1d_field_comparison.py +0/-85    plot_acov_1d.py +0/-122  plot_fields_2d.py +0/-252  plot_hcov_1d.py +0/-137  plot_small_s_behavior.py +0/-87

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Sign Convention The sign corrections in the magnetic field components and vector potential transformations need careful validation. The changes to sqgBctr calculations and coordinate transformations from (s,theta,zeta) to (s,theta*,phi) involve multiple sign flips that could affect field line integration accuracy. ! Jac switches sign from (s, theta, zeta) to (s, theta, phi) sqgBctr(1) = 0.0_dp ! Jac * B^s = 0 (no radial contravariant component) sqgBctr(2) = (-Jac) * Bthctr ! -Jac * B^θ sqgBctr(3) = (-Jac) * (-Bzetactr) ! = Jac * B^ζ = -Jac * -B^ζ = (-Jac) * B^φ end if Bthcov = (g_tt * Bthctr + g_tz * Bzetactr) Bzetacov = (g_tz * Bthctr + g_zz * Bzetactr) ! For theta* coordinates, we need covariant B in s direction Bscov = (g_st * Bthctr + g_sz * Bzetactr) Bmod = sqrt(Bthctr*Bthcov + Bzetactr*Bzetacov) ! Apply theta* coordinate transformations with Lambda derivatives ! The GVEC components are in (s,theta,zeta) but SIMPLE expects (r,theta*,phi) ! where s = r^2, theta* = theta + Lambda, and phi = -zeta ! The transformation requires: ds/dr = 2*r hcov(1) = Bscov / Bmod hcov(2) = Bthcov / Bmod hcov(3) = - Bzetacov / Bmod ! Minus for phi = -zeta ! Vector potential with theta* transformations ! Acov_theta in GVEC is the toroidal flux phi_val Acov(1) = phi_val * dLA_ds * 2.0_dp * r Acov(2) = phi_val * (1.0_dp + dLA_dthet) Acov(3) = - (-chi_val + phi_val * dLA_dzeta) ! Minus for phi = -zeta Type Conversion The variable declarations and type conversions in the grid sampling function may cause precision loss or incorrect grid generation. The conversion from real to integer for grid size calculations and the loop bounds need verification. integer :: xsize, ngrid, ipart, jpart, lidx xsize_real = (2*pi) * grid_density !angle density xsize = int(xsize_real) ngrid = int((1 / grid_density) - 1) ntestpart = ngrid ** 2 !number of total angle points Placeholder Values Multiple placeholder values are used for critical magnetic field quantities like Jacobian, coordinate derivatives, and field components. These dummy values could cause incorrect physics calculations in canonical coordinate transformations. sqg = sqrt(Bmod) ! Placeholder - needs proper Jacobian Bctrvr_vartheta = hcov(2) * Bmod ! Placeholder Bctrvr_varphi = hcov(3) * Bmod ! Placeholder Bcovar_r = Acov(1) ! Placeholder Bcovar_vartheta = Acov(2) ! Placeholder Bcovar_varphi = Acov(3) ! Placeholder

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Prevent division by zero for small s Division by sqrt(s) can cause numerical issues or division by zero when s approaches zero. Add a check to handle the case where s is very small to prevent potential floating-point exceptions. src/field/vmec_field_adapter.f90 [159] -daiota_ds = eval_iota_r(sqrt(s), 1) / (2.0_dp * sqrt(s)) ! Chain rule: d/ds = d/drho * drho/ds +if (s > 1.0e-12_dp) then + daiota_ds = eval_iota_r(sqrt(s), 1) / (2.0_dp * sqrt(s)) ! Chain rule: d/ds = d/drho * drho/ds +else + daiota_ds = 0.0_dp ! Handle s -> 0 limit +end if Apply / Chat Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a potential division-by-zero error when s is zero and provides a robust fix by adding a check, which prevents a runtime crash.	Medium
	Fix unreachable code after error stop The error stop statement prevents the test from running. Either remove this line to allow the test to execute, or move it after the system call if the intention is to fail after attempting execution. test/tests/test_simple_vmec_gvec.f90 [94-95] ! Run SIMPLE with GVEC +call system('../../simple.x test_gvec.in > test_gvec.log') error stop "Requires fully working GVEC field implementation" -call system('../../simple.x test_gvec.in > test_gvec.log') [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies that the call system is unreachable, but this is intentional as the test is marked with WILL_FAIL TRUE in CMakeLists.txt.	Low
General	Fix circular dependency in error message The error message suggests calling field%evaluate first, but this creates a circular dependency since this function is called from within the field evaluation process. Consider removing this check or providing a more appropriate initialization mechanism that doesn't require the user to call the same function they're already calling. src/field/vmec_field_adapter.f90 [40-46] -! Check if GVEC state is properly initialized before evaluation -! This follows the same pattern as field_gvec.f90 +! GVEC state should be initialized by the field object before calling this function +! If not initialized, this indicates a programming error in the field implementation if (.not. allocated(profiles_1d) .or. .not. allocated(sbase_prof) .or. & .not. allocated(X1_r) .or. .not. allocated(X2_r) .or. .not. allocated(LA_r)) then - ! Need to reinitialize GVEC state - error stop 'GVEC state not initialized in vmec_field_adapter - call field%evaluate first' + error stop 'GVEC state not properly initialized - check field implementation' end if Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies that the error message is confusing and improves it to point to a potential internal implementation issue, which is more helpful for debugging.	Low
Update

[krystophny]

ok