Refactor the hybrid solver

[henry2004y]

• Refactor the internal of the hybrid tracing solver
• Add a new demo for the hybrid method

[gemini-code-assist]

Summary of Changes

Hello @henry2004y, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines the adaptive hybrid solver, which intelligently transitions between full orbit and guiding center particle tracing based on local adiabaticity. The changes improve the solver's internal structure and introduce a new demonstration that visually explains its adaptive behavior in a magnetic bottle field. The updated tests ensure robustness across various field conditions, and the added verbosity option aids in debugging and understanding the solver's dynamic operation.

Highlights

• Hybrid Solver Refactoring: The internal implementation of the adaptive hybrid tracing solver has been refactored for improved structure and maintainability.
• New Hybrid Solver Demo: A new example (demo_hybrid.jl) has been added to illustrate the adaptive hybrid solver's functionality, showcasing dynamic switching between Full Orbit (FO) and Guiding Center (GC) modes in a magnetic bottle field.
• Verbose Logging for Hybrid Solver: A verbose option was introduced to the hybrid solver, enabling detailed logging of mode switches (GC ↔ FO) during simulation for better debugging and understanding.
• Enhanced Hybrid Solver Tests: The test suite for the hybrid solver has been significantly expanded with new cases covering adiabatic, non-adiabatic, and dynamic switching scenarios, ensuring robustness across various field conditions.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• docs/examples/features/demo_hybrid.jl
  • Added a new example demonstrating the adaptive hybrid solver, including visualization of particle trajectories and adiabaticity.
• docs/make.jl
  • Updated the documentation build configuration to include the new demo_hybrid.jl example.
• src/boris.jl
  • Removed the @inline macro from the solve function for the Boris method.
• src/hybrid.jl
  • Modified solve and _solve functions to accept a new verbose keyword argument.
  • Applied @inline macro to _solve and _hybrid_adaptive! functions for potential performance benefits.
  • Refined type parameterization for solve and _solve functions.
  • Removed the @fastmath macro from the main loop in _hybrid_adaptive!.
  • Integrated @info logging statements to report initial solver mode and dynamic mode switches (GC ↔ FO) when verbose is enabled.
  • Removed an extraneous empty line before the final save block.
• src/prepare.jl
  • Corrected the indentation of the Field struct's docstring.
• test/test_hybrid.jl
  • Expanded the test suite for the adaptive hybrid solver, adding new test cases for non-adiabatic fields and dynamic switching in a magnetic bottle.
  • Refactored existing tests into let blocks for better scope management.

Activity

• No specific activity (comments, reviews, progress updates) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request refactors the hybrid solver, improving its implementation and adding a verbose option for debugging. It also introduces a comprehensive new demo for the hybrid method and significantly enhances the corresponding test suite to cover more realistic scenarios, such as particle trapping in a magnetic bottle. The changes improve code quality, test coverage, and documentation. I have one suggestion to improve the code style in the new demo file.

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 81.58%. Comparing base (9ab1a7a) to head (0959d05).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/hybrid.jl	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #456      +/-   ##
==========================================
+ Coverage   81.23%   81.58%   +0.35%     
==========================================
  Files          21       21              
  Lines        2025     2026       +1     
==========================================
+ Hits         1645     1653       +8     
+ Misses        380      373       -7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Benchmark Results (Julia v1)

Time benchmarks

	master	0959d05...	master / 0959d05...
interpolation/cartesian	0.14 ± 0.001 μs	0.131 ± 0.011 μs	1.07 ± 0.09
interpolation/spherical	0.44 ± 0.01 μs	0.441 ± 0.01 μs	0.998 ± 0.032
interpolation/time-dependent	4.71 ± 3.9 μs	4.86 ± 4 μs	0.969 ± 1.1
trace/GC/DiffEq Vern6	6.1 ± 1.6 μs	6.32 ± 1.6 μs	0.965 ± 0.35
trace/GC/Native RK4	0.154 ± 0.0005 s	0.153 ± 0.00026 s	1.01 ± 0.0037
trace/GC/Native RK45	3.84 ± 0.15 μs	3.75 ± 0.15 μs	1.02 ± 0.057
trace/Hybrid/Sheared	3.52 ± 0.12 μs	3.5 ± 0.12 μs	1.01 ± 0.049
trace/analytic field/in place	0.0615 ± 0.039 ms	0.0598 ± 0.039 ms	1.03 ± 0.94
trace/analytic field/in place relativistic	0.092 ± 0.04 ms	0.0924 ± 0.04 ms	0.997 ± 0.61
trace/analytic field/out of place	0.0467 ± 0.031 ms	0.0469 ± 0.04 ms	0.996 ± 1.1
trace/normalized/out of place	16.5 ± 9.1 μs	16.5 ± 9.1 μs	0.996 ± 0.78
trace/numerical field/Adaptive Boris	4.53 ± 0.097 ms	4.73 ± 0.33 ms	0.958 ± 0.07
trace/numerical field/Boris	8.01 ± 0.13 μs	8.01 ± 0.11 μs	1 ± 0.021
trace/numerical field/Boris ensemble	16 ± 0.18 μs	16 ± 0.22 μs	0.997 ± 0.018
trace/numerical field/Boris kernel	10.4 ± 0.25 μs	10.4 ± 0.26 μs	1 ± 0.035
trace/numerical field/Boris with fields	8.68 ± 0.12 μs	8.7 ± 0.12 μs	0.998 ± 0.019
trace/numerical field/Multistep Boris	11.9 ± 0.14 μs	11.9 ± 0.13 μs	0.998 ± 0.016
trace/numerical field/in place	28.9 ± 5.9 μs	28.9 ± 5.9 μs	1 ± 0.29
trace/numerical field/out of place	20.5 ± 5.8 μs	21.4 ± 5.9 μs	0.957 ± 0.38
trace/time-dependent field/in place	0.132 ± 0.0053 ms	0.131 ± 0.0059 ms	1 ± 0.06
trace/time-dependent field/out of place	0.11 ± 0.0065 ms	0.109 ± 0.0059 ms	1.01 ± 0.08
time_to_load	2.12 ± 0.0045 s	2.11 ± 0.0054 s	1 ± 0.0033

Memory benchmarks

	master	0959d05...	master / 0959d05...
interpolation/cartesian	2 allocs: 0.234 kB	2 allocs: 0.234 kB	1
interpolation/spherical	2 allocs: 0.203 kB	2 allocs: 0.203 kB	1
interpolation/time-dependent	0.044 k allocs: 9.62 kB	0.044 k allocs: 9.62 kB	1
trace/GC/DiffEq Vern6	0.177 k allocs: 12.2 kB	0.177 k allocs: 12.2 kB	1
trace/GC/Native RK4	13 allocs: 0.382 MB	13 allocs: 0.382 MB	1
trace/GC/Native RK45	16 allocs: 2.44 kB	16 allocs: 2.44 kB	1
trace/Hybrid/Sheared	8 allocs: 2.98 kB	8 allocs: 2.98 kB	1
trace/analytic field/in place	2.07 k allocs: 0.0883 MB	2.07 k allocs: 0.0883 MB	1
trace/analytic field/in place relativistic	2.07 k allocs: 0.0883 MB	2.07 k allocs: 0.0883 MB	1
trace/analytic field/out of place	2.03 k allocs: 0.0866 MB	2.03 k allocs: 0.0866 MB	1
trace/normalized/out of place	0.753 k allocs: 0.0321 MB	0.753 k allocs: 0.0321 MB	1
trace/numerical field/Adaptive Boris	27 allocs: 1.5 MB	27 allocs: 1.5 MB	1
trace/numerical field/Boris	6 allocs: 1.16 kB	6 allocs: 1.16 kB	1
trace/numerical field/Boris ensemble	10 allocs: 2.28 kB	10 allocs: 2.28 kB	1
trace/numerical field/Boris kernel	0.038 k allocs: 2.12 kB	0.038 k allocs: 2.12 kB	1
trace/numerical field/Boris with fields	6 allocs: 1.52 kB	6 allocs: 1.52 kB	1
trace/numerical field/Multistep Boris	6 allocs: 1.16 kB	6 allocs: 1.16 kB	1
trace/numerical field/in place	0.432 k allocs: 20.8 kB	0.432 k allocs: 20.8 kB	1
trace/numerical field/out of place	0.393 k allocs: 18.6 kB	0.393 k allocs: 18.6 kB	1
trace/time-dependent field/in place	3.97 k allocs: 0.177 MB	3.97 k allocs: 0.177 MB	1
trace/time-dependent field/out of place	3.93 k allocs: 0.175 MB	3.93 k allocs: 0.175 MB	1
time_to_load	0.145 k allocs: 11 kB	0.145 k allocs: 11 kB	1