[GSPH] Add GSPH physics module (UpdateDerivs)

[Guo-astro]

Summary

This PR adds the core physics computation module for GSPH.

Depends on: #1451 (Riemann solvers)

Files added

modules/UpdateDerivs.hpp/cpp:

• Main derivative computation using Riemann solver results
• Implements both iterative (van Leer 1997) and HLLC solvers
• Computes acceleration (dv/dt) using interface pressure p*
• Computes energy rate (du/dt) for adiabatic simulations
• Uses shamrock's neighbor cache for efficient particle iteration

Implementation

Follows Cha & Whitworth (2003) formulation:

• Momentum equation: dv_a/dt = -sum_b m_b * p* * (nabla W / (rho^2 * omega))
• Energy equation: du_a/dt = -sum_b m_b * p* * (v* - v_a) dot nabla W / (rho^2 * omega)

For each particle pair:

1. Extract left/right states (rho, v, P)
2. Project velocities onto pair axis
3. Solve 1D Riemann problem to get (p*, v*)
4. Compute force contribution using p* instead of artificial viscosity

CMakeLists.txt updates

• Added UpdateDerivs.cpp to sources
• Added shamtree and shammodels_sph dependencies

References

• Cha & Whitworth (2003) "Implementations and tests of Godunov-type particle hydrodynamics"
• Inutsuka (2002) "Reformulation of SPH with Riemann Solver"

Test plan

• Builds successfully with GSPH infrastructure
• Template instantiations compile for all kernel types (M4, M6, M8, C2, C4, C6)

[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 introduces the foundational Godunov Smoothed Particle Hydrodynamics (GSPH) physics module, a significant enhancement for hydrodynamics simulations. It shifts from conventional SPH artificial viscosity to a more physically rigorous approach by solving 1D Riemann problems at particle interfaces. This allows for the precise calculation of particle acceleration and energy rates, adhering to the well-established Cha & Whitworth (2003) formulation. The module is designed with flexibility, offering various Riemann solver and reconstruction configurations, and integrates seamlessly with existing Shamrock infrastructure for efficient neighbor searching and data handling.

Highlights

• New GSPH Physics Module: Introduced the core physics computation module for Godunov Smoothed Particle Hydrodynamics (GSPH), enabling advanced hydrodynamics simulations.
• Riemann Solver Integration: Implemented both iterative (van Leer 1997) and HLLC Riemann solvers to determine interface pressure (p*) and velocity (v*) at particle interfaces, replacing traditional artificial viscosity.
• Derivative Computation: The module computes acceleration (dv/dt) and energy rate (du/dt) for particles based on the interface pressure derived from the Riemann problem, following the Cha & Whitworth (2003) formulation.
• Efficient Neighbor Interaction: Leverages shamrock's neighbor cache for efficient iteration over particle pairs, optimizing the GSPH force calculation process.
• Comprehensive Configuration: Added extensive configuration options for the GSPH solver, including settings for CFL conditions, unit systems, Riemann solvers, reconstruction methods (PiecewiseConstant, MUSCL with limiters), Equations of State (EOS), boundary conditions, external forces, and tree parameters.

🧠 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.

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 the core GSPH physics module, which is a significant and well-structured addition. The separation of concerns into configuration, storage, and computation modules is commendable. However, I've identified several critical issues that need to be addressed before merging. There is substantial code duplication, particularly in the Riemann solver implementations and the main derivative update loops, which will pose a maintenance challenge. A critical bug exists in the energy equation calculation, where a symmetric formula is incorrectly used for a non-symmetric term. Additionally, there are hardcoded values that make the implementation less robust, such as an assumed value for gamma in the HLLC solver, and magic numbers that should be defined as named constants. I have provided specific comments and code suggestions to resolve these issues.

[y-lapeyre]

Could you close the Gemini conversations when the point was addressed please? To make the discussion clearer :)

[Guo-astro]

Review required

Resolved all Gemini conversations in my newest commit :)

[y-lapeyre]

Ok to me!

[github-actions]

Workflow report

workflow report corresponding to commit 59eeb4a
Commiter email is yona.lapeyre@ens-lyon.fr
GitHub page artifact URL GitHub page artifact link (can expire)

Pre-commit check report

Pre-commit check: ✅

trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check for merge conflicts................................................Passed
check that executables have shebangs.....................................Passed
check that scripts with shebangs are executable..........................Passed
check for added large files..............................................Passed
check for case conflicts.................................................Passed
check for broken symlinks................................................Passed
check yaml...............................................................Passed
detect private key.......................................................Passed
No-tabs checker..........................................................Passed
Tabs remover.............................................................Passed
Validate GitHub Workflows................................................Passed
clang-format.............................................................Passed
black....................................................................Passed
ruff check...............................................................Passed
Check doxygen headers....................................................Passed
Check license headers....................................................Passed
Check #pragma once.......................................................Passed
Check SYCL #include......................................................Passed
No ssh in git submodules remote..........................................Passed

Test pipeline can run.

Clang-tidy diff report

No relevant changes found.
Well done!

You should now go back to your normal life and enjoy a hopefully sunny day while waiting for the review.

Doxygen diff with main

Removed warnings : 1
New warnings : 10
Warnings count : 7578 → 7587 (0.1%)

Detailed changes :

+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:54: warning: Member Tscal (typedef) of class shammodels::gsph::modules::UpdateDerivs is not documented.
+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:55: warning: Member dim (variable) of class shammodels::gsph::modules::UpdateDerivs is not documented.
+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:56: warning: Member Kernel (typedef) of class shammodels::gsph::modules::UpdateDerivs is not documented.
+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:58: warning: Member Config (typedef) of class shammodels::gsph::modules::UpdateDerivs is not documented.
+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:59: warning: Member Storage (typedef) of class shammodels::gsph::modules::UpdateDerivs is not documented.
+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:61: warning: Member context (variable) of class shammodels::gsph::modules::UpdateDerivs is not documented.
+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:62: warning: Member solver_config (variable) of class shammodels::gsph::modules::UpdateDerivs is not documented.
+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:63: warning: Member storage (variable) of class shammodels::gsph::modules::UpdateDerivs is not documented.
+ src/shammodels/gsph/include/shammodels/gsph/modules/UpdateDerivs.hpp:65: warning: Member UpdateDerivs(ShamrockCtx &context, Config &solver_config, Storage &storage) (function) of class shammodels::gsph::modules::UpdateDerivs is not documented.

[tdavidcl]

LGTM