Feature/186 flr losses

[pablo-oyola]

Implemented algorithm described in Issue #187

[Copilot]

Pull request overview

This PR implements finite Larmor radius (FLR) losses for guiding center simulations as described in Issue #187. The feature adds a check during wall collision detection to determine if a particle's gyro-orbit intersects with the wall, even when the guiding center position doesn't. This is accomplished by sampling a random gyrophase, transforming from guiding center to particle coordinates, and checking for wall intersection along that path.

Key Changes:

• Adds new flr_losses_eval() function that samples gyrophase and checks for FLR-induced wall collisions
• Integrates FLR loss checking into the guiding center end condition evaluation (endcond_check_gc)
• Adds new end condition flag endcond_flr_wall to distinguish FLR losses from standard wall collisions

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
src/wall/wall_flr_losses.h	Header file declaring the FLR loss evaluation function (has naming and documentation issues)
src/wall/wall_flr-losses.c	Implementation of FLR loss detection algorithm (filename inconsistency with header)
src/simulate.h	Adds enable_flr_losses flag to simulation options structure
src/simulate.c	Validates that FLR losses are only used in guiding center mode
src/endcond.h	Adds endcond_flr_wall flag to end condition enumeration
src/endcond.c	Integrates FLR loss checking into GC end condition loop and adds parsing/string functions
src/hdf5io/hdf5_options.c	Adds reading of ENABLE_FLR_LOSSES option from HDF5 with validation
a5py/ascotpy/preflight.py	Adds Python-side validation that FLR losses only work with GC mode
a5py/ascotpy/libsimulate.py	Binds enable_flr_losses option to simulation structure (missing int cast)
a5py/ascotpy/ascot2py.py	Auto-generated Python bindings with FLR functions and constants
a5py/ascot5io/options.py	Adds ENABLE_FLR_LOSSES property and XML schema definition
.gitignore	Adds personal development environment entries (questionable for feature PR)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[miekkasarki]

This feature resembles what the hybrid mode was called in ASCOT4, and what the hybrid mode was supposed to be in ASCOT5. We didn't implement this in ASCOT5 because a) I have an issue with randomly guessing the gyroangle and b) due to how the code is parallelized this would slow-down the simulation considerably.

However, we would like to have proper hybrid mode in ASCOT5, so I'm keeping this PR open or store your commits to a feature branch. What this would need at the minimum is a check so that the FLR wall collisions are not checked at every time step (e.g. a scalar field that would store minimum distance to the wall for a given point, and collisions would be checked only if this distance is <= Larmor radius). Then some solution to the random gyroangle issue. The reason I dislike it is that you can have gyroangle vary by PI even in subsequent time steps.