[Users] Geodesic: a test-particle geodesic thorn (AMR-verified) - for today's weekly users call

[Yuhua Li]

Dear all,


At today's weekly users call I would like to briefly present Geodesic, a
new thorn that integrates test-particle geodesics in Kerr--Schild
Cartesian coordinates, and ask for feedback before submitting it to the
Einstein Toolkit.


Features
- Two metric modes: an exact analytic Kerr--Schild metric
  (grid-independent, symbolically verified to be a vacuum solution at
  machine precision), and a grid mode that samples the ADMBase fields
  with three interchangeable samplers selected by one parameter:
  local27 (default, 27-point local Lagrange fit), aei (fourth-order
  pointwise, via AEILocalInterp), and carpet (second-order pointwise
  quadratic Lagrange).
- Adaptive RKF45 integration with per-step renormalization of the
  four-velocity; d_t g recovered from the three most recent ADMBase
  time levels (stationary metrics are auto-detected).
- AMR-ready: each sampler reads the refinement level that contains the
  particle, so geodesics can be integrated inside a Carpet AMR
  evolution (with 4:1 subcycling) without any change to the integrator.
- OpenMP-parallel particle loop: scales to 10^4 particles (9.2x
  speedup, 10.4% efficiency on 88 threads); embedded in a full GRHydro
  evolution, tracking 10^4 particles costs only ~3.1% of the wall time.


Verification
- E, L_z and the norm conserved to ~1e-9 over T = 1000 M on three
  distinct bound orbits (circular, tilted, eccentric).
- Grid convergence of the default sampler with a measured local order
  of 3.7 (formal order three) against an independent reference.
- Five-way comparison of the exact metric and the three samplers on a
  precessing orbit of 200 particles close to the plunge boundary.
- New: on a 3-level Carpet AMR mesh (50^3 base, dx=1; refinement boxes
  of half-width 16/8, factor 2), all three samplers reproduce the
  unigrid reference orbit of conv100 over ~1.05 orbital periods
  (t = 0..150.1): radial deviations 0.4% (local27), 0.5% (aei), 2.3%
  (carpet, consistent with its second formal order), with no lost
  particles and no NaNs.


Code and configurations
- Repository (GPLv2+): https://github.com/wylyhzh/Geodesic
- Includes a 7-test testsuite, ThornGuide documentation, and the
  parameter files used for the results above (including the three
  AMR-vs-unigrid comparison setups).
- A paper describing the implementation and the verification suite is
  in preparation.


Known limitation
- The multi-process (MPI) particle layout is implemented
  (DISTRIB=CONSTANT, rank-0 integration with state synchronization) but
  has not yet been exercised with the current rework; single-process
  OpenMP runs are the tested configuration. The aei sampler in addition
  needs single-process runs or AEILocalInterp's N_boundary_points_omit
  when its fourth-order stencil would cross a processor boundary.


Any feedback is very welcome - in particular on whether the thorn
should be proposed as EinsteinAnalysis/Geodesic.


Best regards,
Yuhua Li
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.einsteintoolkit.org/pipermail/users/attachments/20260917/3eb8acd6/attachment.htm>