doc: improve hybrid demo

[henry2004y]

• Accept trace solution in get_adiabaticity directly
• Improve the demos

[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 significantly improves the get_adiabaticity utility by allowing it to directly consume AbstractODESolution objects, thereby streamlining the process of calculating adiabaticity from simulation results. This enhancement leads to more readable and maintainable demo code, making it easier for users to understand and apply the concepts of hybrid solvers and adiabaticity in particle tracing simulations.

Highlights

• Enhanced Adiabaticity Calculation: Introduced new get_adiabaticity methods that directly accept AbstractODESolution objects, simplifying the calculation of adiabaticity for both Full Orbit (FO) and Guiding Center (GC) traces by automatically extracting necessary parameters.
• Improved Demo Readability: Refactored the demo_proton_dipole.jl and demo_hybrid.jl examples to utilize the new get_adiabaticity overloads, resulting in cleaner and more concise code for computing and displaying adiabaticity.
• Expanded Test Coverage: Added comprehensive unit tests in test_utility.jl for the newly implemented get_adiabaticity methods that dispatch on AbstractODESolution, ensuring their correctness and reliability.

🧠 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/analytic/demo_proton_dipole.jl
  • Updated get_adiabaticity call to accept sol_gc directly.
• docs/examples/features/demo_hybrid.jl
  • Added semicolons for cleaner syntax in variable assignments.
  • Removed save_everystep = true from solve calls for potentially optimized memory usage.
  • Replaced manual compute_adiabaticity functions with direct calls to the new get_adiabaticity overloads for sol_fo, sol_gc, and sol.
• src/utility/utility.jl
  • Added a new get_adiabaticity method that accepts an AbstractODESolution and returns a vector of adiabaticity values, handling both 6-state (FO/Hybrid) and 4-state (GC) solutions.
  • Added another get_adiabaticity method that accepts an AbstractODESolution and a time t, returning the scalar adiabaticity at that specific time.
• test/test_utility.jl
  • Added new test cases for get_adiabaticity to verify its functionality when passed AbstractODESolution objects for both Full Orbit and Guiding Center traces, including vector and scalar outputs.

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 significantly improves the hybrid demo by introducing new get_adiabaticity methods that operate directly on ODESolution objects. This refactoring greatly simplifies the demo code. My review focuses on the new utility functions. I've identified a couple of potential division-by-zero issues in the new get_adiabaticity methods when the magnetic field is zero, and I've also suggested addressing some code duplication to improve long-term maintainability. Overall, these are valuable changes that enhance the clarity and usability of the library's examples.

[codecov]

Codecov Report

❌ Patch coverage is 96.66667% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 81.80%. Comparing base (de5b735) to head (0c31599).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/utility/utility.jl	96.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #457      +/-   ##
==========================================
+ Coverage   81.58%   81.80%   +0.21%     
==========================================
  Files          21       21              
  Lines        2026     2056      +30     
==========================================
+ Hits         1653     1682      +29     
- Misses        373      374       +1     

☔ 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	0c31599...	master / 0c31599...
interpolation/cartesian	0.12 ± 0.011 μs	0.12 ± 0.011 μs	1 ± 0.13
interpolation/spherical	0.411 ± 0.01 μs	0.411 ± 0.01 μs	1 ± 0.034
interpolation/time-dependent	4.29 ± 3.3 μs	4.41 ± 3.2 μs	0.973 ± 1
trace/GC/DiffEq Vern6	5.82 ± 1.4 μs	5.72 ± 1.4 μs	1.02 ± 0.35
trace/GC/Native RK4	0.137 ± 0.00039 s	0.136 ± 6.5e-05 s	1.01 ± 0.0029
trace/GC/Native RK45	3.4 ± 0.13 μs	3.39 ± 0.16 μs	1 ± 0.061
trace/Hybrid/Sheared	3.38 ± 0.1 μs	3.39 ± 0.09 μs	0.997 ± 0.04
trace/analytic field/in place	0.0557 ± 0.033 ms	0.0555 ± 0.033 ms	1 ± 0.84
trace/analytic field/in place relativistic	0.0856 ± 0.034 ms	0.0864 ± 0.034 ms	0.991 ± 0.56
trace/analytic field/out of place	0.045 ± 0.033 ms	0.0453 ± 0.032 ms	0.994 ± 1
trace/normalized/out of place	16.2 ± 7.7 μs	15.8 ± 7.7 μs	1.03 ± 0.7
trace/numerical field/Adaptive Boris	4.23 ± 0.076 ms	4.25 ± 0.083 ms	0.995 ± 0.026
trace/numerical field/Boris	7.35 ± 0.07 μs	7.37 ± 0.08 μs	0.997 ± 0.014
trace/numerical field/Boris ensemble	14.7 ± 0.15 μs	14.7 ± 0.16 μs	0.997 ± 0.015
trace/numerical field/Boris kernel	9.44 ± 0.17 μs	9.5 ± 0.17 μs	0.994 ± 0.025
trace/numerical field/Boris with fields	8 ± 0.071 μs	8 ± 0.08 μs	1 ± 0.013
trace/numerical field/Multistep Boris	11 ± 0.09 μs	11 ± 0.081 μs	1 ± 0.011
trace/numerical field/in place	27.2 ± 4.8 μs	27.3 ± 4.9 μs	0.998 ± 0.25
trace/numerical field/out of place	19.1 ± 4.8 μs	19.2 ± 4.7 μs	0.991 ± 0.35
trace/time-dependent field/in place	0.136 ± 0.0053 ms	0.138 ± 0.0078 ms	0.984 ± 0.067
trace/time-dependent field/out of place	0.109 ± 0.006 ms	0.107 ± 0.0055 ms	1.02 ± 0.077
time_to_load	2.22 ± 0.042 s	2.23 ± 0.054 s	0.996 ± 0.031

Memory benchmarks

	master	0c31599...	master / 0c31599...
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.1 kB	0.177 k allocs: 12.1 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.0865 MB	2.03 k allocs: 0.0865 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.7 kB	0.432 k allocs: 20.7 kB	1
trace/numerical field/out of place	0.393 k allocs: 18.5 kB	0.393 k allocs: 18.5 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