[GSPH 4/7] SR Riemann solver and mode implementation

[Guo-astro]

Summary

Completes the SR-GSPH implementation with Riemann solvers and mode orchestration.

Recovery Methods

• RecoveryBase: abstract interface for primitive recovery
• NewtonRaphson: Newton-Raphson iterative recovery algorithm for conservative-to-primitive conversion

Riemann Solvers

• RiemannBase: abstract SR Riemann solver interface
• Exact: exact relativistic Riemann solver following Pons et al. (2000)

Mode Implementation

• SRMode.cpp: complete SR physics mode orchestration
  • Ghost field setup for SR variables (Lorentz factor, momentum, etc.)
  • Primitive recovery from conserved variables
  • Force computation with relativistic corrections
  • Integration of SR equations

Physics Background

• Implements exact relativistic Riemann solver (Pons 2000)
• Newton-Raphson primitive recovery for robustness
• Full SR-GSPH physics loop following Kitajima 2024

Dependencies

Depends on #1525 (SR physics core)

[github-actions]

Thanks @Guo-astro for opening this PR!

You can do multiple things directly here:
1 - Comment pre-commit.ci run to run pre-commit checks.
2 - Comment pre-commit.ci autofix to apply fixes.
3 - Add label autofix.ci to fix authorship & pre-commit for every commit made.
4 - Add label light-ci to only trigger a reduced & faster version of the CI (need the full one before merge).
5 - Add label trigger-ci to create an empty commit to trigger the CI.

Once the workflow completes a message will appear displaying informations related to the run.

Also the PR gets automatically reviewed by gemini, you can:
1 - Comment /gemini review to trigger a review
2 - Comment /gemini summary for a summary
3 - Tag it using @gemini-code-assist either in the PR or in review comments on files

[gemini-code-assist]

Summary of Changes

Hello @Guo-astro, 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 extends the Special Relativistic Smoothed Particle Hydrodynamics (SR-GSPH) framework by integrating essential components for relativistic fluid simulations. It provides a robust mechanism for interconverting conserved and primitive fluid variables, introduces an exact Riemann solver capable of accurately modeling relativistic wave phenomena, and establishes a comprehensive physics mode to manage the full simulation lifecycle, ensuring both physical accuracy and numerical resilience.

Highlights

• Primitive Recovery Implementation: Introduced RecoveryBase as an abstract interface for primitive recovery in Special Relativistic Smoothed Particle Hydrodynamics (SR-GSPH). A concrete NewtonRaphson implementation was added to convert conserved variables (momentum, energy, lab-frame density) into primitive variables (Lorentz factor, rest-frame density, pressure, velocities) by solving a quartic equation for the Lorentz factor.
• Exact Relativistic Riemann Solver: A new RiemannBase interface and an Exact relativistic Riemann solver have been implemented. This solver, based on Pons et al. (2000), uses a hybrid Newton-bisection method to determine the interface states (pressure, normal and tangential velocities) by resolving relativistic shocks and rarefaction waves, including numerical integration via Gauss-Legendre quadrature for rarefactions with tangential velocities.
• Comprehensive SR Physics Mode: The SRMode class has been added to orchestrate the entire SR-GSPH timestep sequence. This includes managing predictor-corrector steps, handling boundary conditions, performing h-iteration with a volume-based smoothing length, initializing and recovering primitive/conserved variables, computing forces using the new exact Riemann solver, and calculating the CFL timestep.
• Enhanced Numerical Stability and Diagnostics: Integrated robust checks throughout the SRMode to detect and report NaN/Inf values in primitive recovery and force derivatives, providing early warnings for numerical instabilities. The implementation also includes clamping mechanisms to prevent superluminal velocities, contributing to overall simulation stability.
• Volume-Based Smoothing Length Iteration: The h-iteration loop for smoothing length calculation has been adapted for SR-GSPH, utilizing a volume-based approach (compute_omega_sr) as described by Kitajima et al. (2025). This method computes the lab-frame baryon density (N) directly from kernel summation and iteratively adjusts the smoothing length based on particle volume.

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 introduces a comprehensive Special Relativistic (SR) hydrodynamics mode for GSPH, including new implementations for primitive recovery and an exact Riemann solver. The NewtonRaphson.hpp file provides a Newton-Raphson method to convert conserved variables to primitives, while Exact.hpp implements an iterative SR Riemann solver based on Pons et al. (2000), featuring Gauss-Legendre quadrature for rarefaction waves and robust bracketing for root finding. Corresponding RecoveryBase.hpp and RiemannBase.hpp files define interfaces and configuration structs for these solvers. The SRMode.cpp file orchestrates the SR simulation timestep, managing predictor-corrector steps, volume-based h-iteration, EOS computations, and force calculations using the new SR solvers. Key changes include the introduction of SR-specific conserved fields (momentum 'S', energy 'e') and lab-frame density 'N'.

Review comments primarily focus on improving robustness, consistency, and error handling. Several comments highlight inconsistencies between the Result structs defined in the base interface headers (RecoveryBase.hpp, RiemannBase.hpp) and their concrete implementations (NewtonRaphson.hpp, Exact.hpp), particularly regarding converged and iterations flags, and the lack of proper Config object usage in the solver functions. A major point of feedback concerns the extensive use of printf for error reporting, recommending replacement with structured logging or exceptions for better system integration and debugging. Numerical stability is also addressed, with suggestions to use sycl::fmax to prevent sqrt(negative) and to handle edge cases (e.g., very small denominators, non-positive mass flux) more explicitly rather than silently returning default values. Additionally, the complexity of the first-timestep initialization logic in SRMode.cpp and the direct modification of global configuration are noted as areas for potential streamlining and improved design.

[Guo-astro]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant feature: a complete Special Relativistic (SR) Godunov SPH (GSPH) implementation. This includes a Newton-Raphson primitive recovery scheme, an exact SR Riemann solver based on Pons et al. (2000), and the main SRMode to orchestrate the simulation loop. The code is well-structured and includes many robustness checks, which is excellent for numerical hydrodynamics. My review focuses on improving consistency, robustness, and maintainability. Key suggestions include aligning implementations with their abstract interfaces, ensuring consistent use of physical units, replacing printf in device code with more appropriate error handling, and some minor code simplifications.