booz_xform input

[krystophny]

PR Type

Enhancement, Tests, Documentation

---

Description

• Added comprehensive BOOZXFORM magnetic field support to SIMPLE, including new BoozXformField module with NetCDF file loading and field evaluation capabilities
• Integrated BOOZXFORM field type (ID=5) into the magnetic field interface with coordinate transformation and derivative computation
• Created extensive test framework with Python comparison scripts for validating field evaluation, coordinate transformations, and particle orbit analysis
• Added configuration parameters and input file templates for BOOZXFORM field type testing
• Implemented performance benchmarking tools comparing VMEC vs BOOZXFORM field evaluation
• Enhanced build system with CMake integration and CTest-compatible test scripts
• Added comprehensive TODO documentation outlining implementation priorities and known issues

---

Diagram Walkthrough

flowchart LR
  A["NetCDF BOOZXFORM Files"] --> B["field_booz_xform.f90"]
  B --> C["BoozXformField Type"]
  C --> D["magfie.f90 Interface"]
  D --> E["Field Evaluation"]
  F["Configuration Files"] --> G["Test Framework"]
  G --> H["Python Comparison Scripts"]
  H --> I["Validation Results"]
  E --> J["Particle Tracing"]
  J --> K["Performance Benchmarks"]

Loading

File Walkthrough

	Relevant files
Enhancement	4 files field_booz_xform.f90 Add BOOZXFORM magnetic field module                                            src/field/field_booz_xform.f90 • New module implementing magnetic field evaluation from BOOZXFORM NetCDF files • Provides BoozXformField type extending MagneticField base class • Includes NetCDF file loading, field evaluation, and memory cleanup routines • Implements simplified coordinate transformation for Boozer coordinates +457/-0  magfie.f90 Integrate BOOZXFORM field type into magnetic field interface src/magfie.f90 • Added BOOZXFORM=5 field type constant and module-level variables • Extended init_magfie to handle BOOZXFORM field initialization • Implemented magfie_boozxform subroutine for field evaluation • Added finite difference computation for field derivatives +115/-1  field_can.f90 Add BOOZXFORM support to canonical field interface              src/field_can.f90 • Added BOOZXFORM import and case handling in field initialization • Extended field_can_from_name and name_from_id functions • Added placeholder handling for BOOZXFORM coordinate transformations +10/-1    simple_main.f90 Add BOOZXFORM file parameter handling to main routine        src/simple_main.f90 • Added boozxform_file parameter import and filename setting logic • Extended run subroutine to handle BOOZXFORM field type initialization • Added validation for required BOOZXFORM filename parameter +10/-2
Configuration changes	7 files params.f90 Add BOOZXFORM file parameter to configuration                        src/params.f90 • Added boozxform_file character parameter for NetCDF filename • Extended namelist configuration to include new parameter +2/-1      Makefile Makefile for VMEC purely toroidal field workflow                  draft/Makefile • Created Makefile for VMEC workflow with purely toroidal field configuration • Added targets for downloading input files and running VMEC simulation • Included clean target for removing generated files +13/-0    simple_vmec.in SIMPLE configuration for VMEC Boozer field testing              test_boozxform/simple_vmec.in • Created SIMPLE configuration file for VMEC field type testing • Set parameters for 10001 timesteps with 128 test particles • Configured Boozer field type (isw_field_type = 2) with VMEC input +8/-0      simple.in Basic SIMPLE configuration template for Boozer fields        draft/simple.in • Created basic SIMPLE configuration template for Boozer field type • Set standard parameters for particle tracing with 128 test particles • Configured for VMEC input with Boozer coordinate conversion +7/-0      simple.in Enhanced example configuration with timestep parameter      examples/simple.in • Added ntimstep = 10001 parameter to existing configuration • Enhanced example configuration with explicit timestep specification +1/-0      CMakeLists.txt CMake integration for booz_xform field module                        src/CMakeLists.txt • Added field/field_booz_xform.f90 to SOURCES list • Integrated new booz_xform field module into build system +1/-0      simple_main Git subproject reference for golden record baseline            golden_record/simple_main • Added Git subproject reference to commit 31e7fe4 • Established golden record baseline for simple_main functionality +1/-0
Tests	15 files test_booz_xform.f90 Add basic BOOZXFORM test program structure                              test/tests/test_booz_xform.f90 • Created minimal test program structure for BOOZXFORM functionality • Empty main subroutine as placeholder for future test implementation +9/-0      compare_boozer_coords.py Add Python comparison script for Boozer coordinates            test/booz_xform/compare_boozer_coords.py • Python script for comparing SIMPLE's internal Boozer vs BOOZXFORM coordinates • Includes NetCDF file reading, coordinate transformation comparison, and plotting • Provides analysis of rotational transform profiles and Fourier spectra +318/-0  compare_field_evaluation.py Add field evaluation comparison script                                      test/booz_xform/compare_field_evaluation.py • Python script comparing magnetic field evaluation between internal Boozer and BOOZXFORM • Creates temporary configurations and evaluates fields at multiple coordinates • Generates comparison plots and statistical analysis of differences +309/-0  plot_orbit_comparison.py Add orbit comparison plotting script                                          test_boozxform/plot_orbit_comparison.py • Script for comparing particle orbits between VMEC and BOOZXFORM field types • Runs SIMPLE twice with different field configurations and plots results • Includes Poincaré section analysis and statistical comparison +193/-0  test_improved_evaluation.py Add BOOZXFORM evaluation validation test                                  test/booz_xform/test_improved_evaluation.py • Test script validating BOOZXFORM field evaluation implementation • Checks for realistic field values vs placeholder data • Tests coordinate variations and provides diagnostic output +196/-0  compare_simsopt.py Add SIMSOPT comparison validation script                                  draft/compare_simsopt.py • Comparison script between SIMPLE and SIMSOPT magnetic field evaluations • Includes field derivative and covariant component comparisons • Provides validation against external reference implementation +180/-0  benchmark_boozxform.py Add BOOZXFORM performance benchmark script                              benchmark/benchmark_boozxform.py • Benchmark script comparing performance of VMEC vs BOOZXFORM field evaluation • Measures execution time and confinement fraction differences • Creates performance comparison plots and statistics +165/-0  plot_existing_results.py Add existing results plotting utility                                        test_boozxform/plot_existing_results.py • Script for plotting results from existing test runs • Compares internal Boozer vs BOOZXFORM field type results • Analyzes confinement evolution and particle loss statistics +148/-0  setup_booz_xform_test.sh Add test environment setup script                                                test/booz_xform/setup_booz_xform_test.sh • Shell script for downloading test data and setting up test environment • Downloads BOOZXFORM and VMEC files from external repositories • Creates test configuration files automatically +50/-0    run_comparison_test.sh Add CTest integration script for comparisons                          test/booz_xform/run_comparison_test.sh • CTest-compatible script for running BOOZXFORM comparison tests • Downloads required files and executes Python comparison scripts • Validates test completion and output generation +54/-0    CMakeLists.txt CMake configuration for booz_xform testing framework          test/tests/CMakeLists.txt • Added test_booz_xform.x executable target linking to simple library • Created test_booz_xform test case • Added test_booz_xform_comparison test with Python environment setup • Configured test properties with timeout and labels +16/-0    test_boozxform_simple.in Test configuration for booz_xform field evaluation              test/booz_xform/test_boozxform_simple.in • Created test configuration for booz_xform field type (isw_field_type = 5) • Set minimal test parameters with single particle and short trace time • Configured both VMEC and booz_xform input files +12/-0    simple.in Reactor-scale booz_xform test configuration                            test_boozxform/simple.in • Created SIMPLE input file for booz_xform testing with reactor-scale configuration • Set field type 5 for booz_xform with RK integrator mode • Configured single particle simulation with short timesteps +10/-0    test_boozxform_simple.in Minimal booz_xform validation test configuration                  test_boozxform_simple.in • Created minimal test configuration for booz_xform field type validation • Set single particle with short trace time for quick testing • Configured both VMEC and booz_xform file inputs +8/-0      simple.in Booz_xform field type test configuration                                  test/booz_xform/simple.in • Created test configuration for booz_xform field type with minimal parameters • Set single particle simulation with short trace time • Configured field type 5 for booz_xform evaluation +9/-0
Formatting	1 files example.py Refactor example code formatting and imports                          examples/example.py • Reformatted code with consistent spacing and import organization • Updated import statement to use pysimple as ps alias • Minor code style improvements and comment formatting +72/-61
Miscellaneous	2 files pysimple.py Add symbolic link to pysimple module                                          draft/pysimple.py • Symbolic link to build directory pysimple module • Provides convenient access to Python bindings +1/-0      benchmark_orbit Symbolic link to benchmark orbit directory                              benchmark_orbit • Created symbolic link to ../benchmark_orbit • Established reference to benchmark orbit functionality +1/-0
Documentation	1 files TODO.md Comprehensive TODO documentation for booz_xform integration TODO.md • Added comprehensive TODO document for booz_xform integration into SIMPLE • Documented implementation tasks with high/medium/low priority levels • Listed completed features including NetCDF reader, field evaluation, and test framework • Identified known issues with 2D array loading and coordinate transformation +105/-0

---

[qodo-code-review]

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

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 Possible Issue The evaluation currently equates VMEC and Boozer angles (theta_b=theta_v, zeta_b=zeta_v) and ignores the provided pmns/gmn transforms, which can yield incorrect B, geometry, and Jacobian. This simplification should be validated or replaced with the proper angle transform using pmns/gmn. ! For now, use VMEC angles directly as Boozer angles (simplified) ! This is not the full transformation but should allow basic evaluation theta_b = theta_v zeta_b = zeta_v Numerical Stability Finite-difference step and coordinate handling may cause domain errors (e.g., sqrt(x(1)-hs) for small s) and division by zero in dr/ds or sqrt(g) computations. Add guards and choose steps in native coords (s,θ,ζ) rather than mixing r=√s. API/Config Coupling Using a module-global filename and lazy-loading inside magfie_boozxform ties runtime behavior to global state and prints extensively. Consider passing filename via init path, removing debug prints, and ensuring thread-safety/reentrancy. integer, parameter :: TEST=-1, CANFLUX=0, VMEC=1, BOOZER=2, MEISS=3, ALBERT=4, BOOZXFORM=5 ! Module-level variable for BOOZXFORM field type(BoozXformField), save :: booz_field logical, save :: booz_field_loaded = .false. character(256) :: boozxform_filename = '' contains subroutine init_magfie(id) integer, intent(in) :: id print *, 'init_magfie: called with id =', id select case(id) case(TEST) print *, 'init_magfie: magfie_test not implemented' error stop case(CANFLUX) print *, 'init_magfie: setting magfie => magfie_can' magfie => magfie_can case(VMEC) print *, 'init_magfie: setting magfie => magfie_vmec' magfie => magfie_vmec case(BOOZER) print *, 'init_magfie: setting magfie => magfie_boozer' magfie => magfie_boozer case(MEISS) print *, 'init_magfie: setting magfie => magfie_meiss' magfie => magfie_meiss case(ALBERT) print *, 'init_magfie: setting magfie => magfie_albert' magfie => magfie_albert case(BOOZXFORM) print *, 'init_magfie: setting magfie => magfie_boozxform' print *, 'init_magfie: boozxform_filename =', trim(boozxform_filename) magfie => magfie_boozxform ! Set default filename for testing - should be set by caller if (trim(boozxform_filename) == '') then boozxform_filename = 'boozmn_LandremanPaul2021_QA_lowres.nc' end if case default

[qodo-code-review]

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

CI Feedback 🧐

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: Run Tests + Generate Coverage

Failed stage: Run Tests with Coverage [❌]

Failed test name: test_booz_xform_comparison

Failure summary: The action failed because CTest reported a failing test: - Test test_booz_xform_comparison (Test #14) failed with message permission denied. - As a result, CTest exited with errors and make test-fast returned a non-zero status (Makefile:33), causing the workflow to exit with code 2.

Relevant error logs: 1: Runner name: 'debian-2' 2: Runner group name: 'default' ... 413: /home/ert/actions-runner-2/_work/SIMPLE/SIMPLE/src/test_collis.f90:10:36: 414: 10 | double precision :: n_d=4.0d0, n_e=2.0d0 ! Test particle mass and charge no. 415: | 1 416: Warning: Unused variable ‘n_e’ declared at (1) [-Wunused-variable] 417: f951: note: unrecognized command-line option ‘-Wno-external-argument-mismatch’ may have been intended to silence earlier diagnostics 418: [205/357] Building Fortran object test/tests/CMakeFiles/test_lapack_interfaces.x.dir/test_lapack_interfaces.f90.o 419: [206/357] Building Fortran object libneo/CMakeFiles/neo.dir/src/arnoldi.f90.o 420: [207/357] Building Fortran object libneo/CMakeFiles/neo.dir/src/nctools_module.f90.o 421: [208/357] Building Fortran object src/CMakeFiles/simple.dir/field/psi_transform.f90.o 422: [209/357] Building Fortran object test/tests/CMakeFiles/test_array_utils.x.dir/test_array_utils.f90.o 423: /home/ert/actions-runner-2/_work/SIMPLE/SIMPLE/test/tests/test_array_utils.f90:115:16: 424: 115 | integer :: k 425: | 1 426: Warning: Unused variable ‘k’ declared at (1) [-Wunused-variable] 427: /home/ert/actions-runner-2/_work/SIMPLE/SIMPLE/test/tests/test_array_utils.f90:6:14: 428: 6 | integer :: i, errors 429: | 1 ... 6540: Start 7: test_timing 6541: 7/15 Test #7: test_timing ...................... Passed 0.09 sec 6542: Start 8: test_sorting 6543: 8/15 Test #8: test_sorting ..................... Passed 0.00 sec 6544: Start 9: test_lapack_interfaces 6545: 9/15 Test #9: test_lapack_interfaces ........... Passed 0.00 sec 6546: Start 10: test_orbit_symplectic_base 6547: 10/15 Test #10: test_orbit_symplectic_base ....... Passed 0.00 sec 6548: Start 11: test_field_base 6549: 11/15 Test #11: test_field_base .................. Passed 0.00 sec 6550: Start 12: test_coordinates_simple 6551: 12/15 Test #12: test_coordinates_simple .......... Passed 0.00 sec 6552: Start 13: test_booz_xform 6553: 13/15 Test #13: test_booz_xform .................. Passed 0.00 sec 6554: Start 14: test_booz_xform_comparison 6555: 14/15 Test #14: test_booz_xform_comparison .......***Failed 0.00 sec 6556: permission denied 6557: Start 16: golden_record_sanity 6558: 15/15 Test #16: golden_record_sanity ............. Passed 0.55 sec 6559: 93% tests passed, 1 tests failed out of 15 6560: Label Time Summary: 6561: booz_xform = 0.00 sec*proc (1 test) 6562: Errors while running CTest 6563: comparison = 0.00 sec*proc (1 test) 6564: make: *** [Makefile:33: test-fast] Error 8 6565: Total Test time (real) = 11.91 sec 6566: The following tests FAILED: 6567: 14 - test_booz_xform_comparison (Failed) booz_xform comparison 6568: ##[error]Process completed with exit code 2. 6569: Cleaning up orphan processes

[qodo-code-review]

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Incomplete Boozer transformation The BOOZXFORM evaluation currently assumes theta_vmec=zeta_vmec equals Boozer angles and sets several quantities via simplified formulae, which will yield systematically incorrect B, Jacobian, and derivatives across the codebase. Implement the full VMEC↔Boozer transformation using pmns/gmn (p and g) and correct packed-index handling (jlist/pack_rad), ensuring |B|, I, G, sqrt(g), and derivatives are evaluated in true Boozer coordinates before interfacing with magfie. Examples: src/field/field_booz_xform.f90 [274-275] !> Note: This is a simplified implementation that evaluates B directly in Boozer coordinates !> without the full coordinate transformation src/field/field_booz_xform.f90 [346-349] ! For now, use VMEC angles directly as Boozer angles (simplified) ! This is not the full transformation but should allow basic evaluation theta_b = theta_v zeta_b = zeta_v Solution Walkthrough: Before: subroutine evaluate_booz_xform(self, x, ...) ! Input x is (r, theta_vmec, zeta_vmec) s = x(1)**2 theta_v = x(2) zeta_v = x(3) ! Incorrectly assume VMEC angles are Boozer angles theta_b = theta_v zeta_b = zeta_v ! Evaluate all quantities using incorrect angles B_booz = sum(bmnc * cos(m*theta_b - n*zeta_b)) ... end subroutine After: subroutine evaluate_booz_xform(self, x, ...) ! Input x is (r, theta_vmec, zeta_vmec) s = x(1)**2 theta_v = x(2) zeta_v = x(3) ! Iteratively solve for true Boozer angles ! theta_b = theta_v - p(theta_b, zeta_b) ! zeta_b = zeta_v - g(theta_b, zeta_b) call solve_for_boozer_angles(s, theta_v, zeta_v, theta_b, zeta_b) ! Evaluate all quantities using correct angles B_booz = sum(bmnc * cos(m*theta_b - n*zeta_b)) ... end subroutine Suggestion importance[1-10]: 9 __ Why: This suggestion correctly identifies a critical flaw where the coordinate transformation is skipped, making the entire BOOZXFORM evaluation produce incorrect results.	High
Possible issue	Fix radial derivative near boundaries Guard against negative or out-of-range s in the finite-difference stencil and use a step in r consistent with evaluate’s input. When near the axis or edge, switch to a one-sided difference to avoid NaNs and out-of-bounds indexing. src/magfie.f90 [485-490] -! Derivative with respect to s -x_plus = [sqrt(x(1) + hs), theta, phi] -x_minus = [sqrt(x(1) - hs), theta, phi] -call booz_field%evaluate(x_plus, Acov_plus, hcov_plus, Bmod_plus) -call booz_field%evaluate(x_minus, Acov_minus, hcov_minus, Bmod_minus) -bder(1) = (Bmod_plus - Bmod_minus) / (2.0d0 * hs * bmod) +! Derivative with respect to s using safe finite differences in r = sqrt(s) +real(dp) :: r_step, s_plus, s_minus +r_step = 1.0d-5 ! small step in r +! central difference by default +if (r > r_step .and. (r + r_step) <= 1.0d0) then + x_plus = [r + r_step, theta, phi] + x_minus = [r - r_step, theta, phi] + call booz_field%evaluate(x_plus, Acov_plus, hcov_plus, Bmod_plus) + call booz_field%evaluate(x_minus, Acov_minus, hcov_minus, Bmod_minus) + ! dB/ds = dB/dr * dr/ds = dB/dr * (1/(2r)) + bder(1) = ((Bmod_plus - Bmod_minus) / (2.0d0 * r_step)) * (0.5d0 / max(r,1.0d-12)) +else + ! one-sided near boundaries + if (r <= r_step) then + x_plus = [r + r_step, theta, phi] + call booz_field%evaluate(x_plus, Acov_plus, hcov_plus, Bmod_plus) + bder(1) = ((Bmod_plus - bmod) / r_step) * (0.5d0 / max(r,1.0d-12)) + else + x_minus = [max(r - r_step, 0.0d0), theta, phi] + call booz_field%evaluate(x_minus, Acov_minus, hcov_minus, Bmod_minus) + bder(1) = ((bmod - Bmod_minus) / r_step) * (0.5d0 / max(r,1.0d-12)) + end if +end if [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a bug where sqrt of a negative number can occur when x(1) is small, leading to NaNs. The proposed fix is robust, using one-sided differences near boundaries to prevent this critical numerical issue.	High
	Guard against zero-division in B Prevent division by zero when B_booz is extremely small and ensure outputs remain finite. Add small positive floors to denominators and clamp Bmod to a minimum to avoid NaNs propagating downstream. src/field/field_booz_xform.f90 [396-418] -! Compute sqrt(g) for Boozer coordinates -! In Boozer coords: sqrt(g) = (G + iota*I) / B^2 -sqrtg = (G_local + iota_local * I_local) / (B_booz * B_booz) -... +! Safe computation guarding against tiny B +real(dp), parameter :: epsB = 1.0e-12_dp +Bmod = max(B_booz, epsB) +sqrtg = (G_local + iota_local * I_local) / max(Bmod*Bmod, epsB) ! Normalized covariant B components hcov(1) = Bcov_s / Bmod hcov(2) = Bcov_theta / Bmod hcov(3) = Bcov_zeta / Bmod [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a potential division-by-zero error if B_booz is zero or very small, which could lead to NaN or Inf values. The proposed change prevents this by flooring the denominator, which is a critical fix for numerical stability.	Medium
General	Robustly read symmetry flag Handle absence or differing naming of the symmetry flag robustly to avoid using an uninitialized lasym_b. Default to .false. and only override when the read succeeds, checking both common variable names. src/field/field_booz_xform.f90 [133-138] -! Check stellarator symmetry +! Default to symmetric unless explicitly read +this%lasym_b = .false. ierr = nf90_inq_varid(ncid, 'lasym__logical__', varid) if (ierr == nf90_noerr) then ierr = nf90_get_var(ncid, varid, lasym_int) - this%lasym_b = (lasym_int == 1) + if (ierr == nf90_noerr) this%lasym_b = (lasym_int == 1) +else + ! Try alternative naming found in some files + ierr = nf90_inq_varid(ncid, 'lasym_b', varid) + if (ierr == nf90_noerr) then + ierr = nf90_get_var(ncid, varid, lasym_int) + if (ierr == nf90_noerr) this%lasym_b = (lasym_int == 1) + end if end if Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that this%lasym_b could be uninitialized. By setting a default value and checking for alternative variable names, it makes the file loading more robust and prevents undefined behavior.	Medium
	Add robust error handling With set -e, any command failure (including python3 or missing script) will abort without a clear message. Add explicit checks and error messages around the script path and Python execution to aid CI diagnosis. test/booz_xform/run_comparison_test.sh [45] set -e # Exit on error ... -python3 ${SCRIPT_DIR}/compare_boozer_coords.py +if [ ! -f "${SCRIPT_DIR}/compare_boozer_coords.py" ]; then + echo "Error: comparison script not found at ${SCRIPT_DIR}/compare_boozer_coords.py" + exit 1 +fi +echo "Running comparison..." +if ! python3 "${SCRIPT_DIR}/compare_boozer_coords.py"; then + echo "Error: comparison script failed" + exit 1 +fi [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies that adding explicit checks for the script's existence and execution failure improves error reporting, which is helpful for debugging CI failures.	Low
More