Add SPH pairing instability test example

[Guo-astro]

Summary

Add example script for testing the pairing instability in SPH with Square and FCC lattice configurations using M4 cubic spline kernel.

Background

The pairing instability is a well-known numerical artifact in SPH where particles on regular grids tend to cluster in pairs. This test compares Square vs FCC lattice behavior.

Configuration

Environment variables:

• PAIRING_LATTICE: square or fcc (default: square)
• PAIRING_N: Grid resolution (default: 64)
• PAIRING_END_TIME: Simulation end time (default: 1.0)
• PAIRING_N_OUTPUTS: Number of VTK outputs (default: 50)

Usage

# Run square lattice simulation
PAIRING_LATTICE=square ./shamrock --sycl-cfg 0:0 --rscript exemples/stability/pairing_instability/pairing_instability.py

# Run FCC lattice simulation  
PAIRING_LATTICE=fcc ./shamrock --sycl-cfg 0:0 --rscript exemples/stability/pairing_instability/pairing_instability.py

GIF animation is generated automatically at the end of each simulation run (requires pyvista, imageio, PIL).

Test Plan

• Verified simulation runs for both Square and FCC lattices
• Verified GIF generation produces animations
• Pre-commit checks pass (ruff, black)

[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 adds a comprehensive example for testing the SPH pairing instability, a critical numerical artifact in particle-based simulations. It provides a simulation setup that compares the stability of square and FCC initial particle lattices, alongside a robust visualization tool to generate animated GIFs from the simulation results. This allows users to easily observe and understand how initial particle arrangements influence the development of the instability, contributing to better understanding and validation of SPH methods.

Highlights

• New SPH Pairing Instability Test: Introduces a new test example to investigate the well-known numerical artifact of pairing instability in Smoothed Particle Hydrodynamics (SPH) simulations.
• Dual Lattice Configurations: The simulation script supports both Square and Face-Centered Cubic (FCC) lattice configurations for initial particle placement, allowing for a direct comparison of their behavior regarding pairing instability.
• M4 Cubic Spline Kernel: Both lattice configurations utilize the M4 cubic spline kernel, a common choice in SPH, for consistency in the test.
• Automated GIF Generation: A dedicated Python script (generate_gifs.py) is included to create annotated GIF animations from the VTK output files, providing clear visual evidence of the instability's evolution.
• Configurable Simulation Parameters: Key simulation parameters such as lattice type, grid resolution, end time, number of outputs, and random seed can be configured via environment variables, enhancing flexibility for testing.

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 adds two new example scripts for testing SPH pairing instability. The simulation script pairing_instability.py and the visualization script generate_gifs.py are well-structured and documented.

My review focuses on improving code style, performance, and robustness. For pairing_instability.py, I've suggested vectorizing the particle generation loops using NumPy, which is more idiomatic and performant. For generate_gifs.py, I've pointed out some style improvements regarding imports and resource management, suggested making command-line arguments mutually exclusive for better user experience, and recommended reading simulation parameters from the metadata file to make the script more robust.

[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