[Users] New thorn proposal: Geodesic — test-particle geodesic tracking for the Einstein Toolkit

Wed Sep 9 12:53:47 CDT 2026

Dear all, dear Steve,

(Continuing the discussion on the list, as suggested.)

Thank you, Steve, for the review of the thorn and the paper draft. The
evaluation gave me a clear roadmap, and I have now completed the rework
in two stages; everything is pushed to
https://github.com/wylyhzh/Geodesic.

First stage (mechanical fixes):

- geodesics_integrate runs with OPTIONS: global and declares READS on
  the ADMBase metric; Geodesic_ParamCheck is actually scheduled;
- the particle arrays are DISTRIB=CONSTANT and checkpointable; the
  unused CoordGauge inherit and the hard KerrSchild dependency are gone
  (the thorn has its own M, a parameters for the exact mode);
- code fixes: the metric inversion no longer returns a garbage inverse
  on singular pivots; the interpolation domain guard matches the
  6th-order stencil; Cactus logging was moved out of the OpenMP loop;
  omp.h is guarded by _OPENMP;
- par/example.par now uses only public thorns and runs on a stock ET
  checkout; the README states the current limitations explicitly
  (unigrid, single refinement level, particle arrays replicated on
  every rank).

Second stage (tests, documentation, robustness):

- Testsuite: test/ now contains three tests, all passing under the
  Cactus testsuite harness: circ_orbit (full particle state compared
  against reference data), circ_orbit_conserved (a postproc checks that
  E and L_z stay constant), and circ_orbit_mpi (the same run on 2 MPI
  ranks, bit-identical to the single-rank result);
- Documentation: doc/documentation.tex (ThornGuide format) is included;
- particle loss handling is now a run-time policy
  (particle_loss_policy = drop / flag / respawn), with drop as the
  default;
- the per-particle cache is allocated once and reused across steps,
  which removes the per-step allocation churn the review pointed out.

The remaining architectural items (correct behaviour with more than one
MPI rank, interpolation through CarpetInterp/AEILocalInterp, and the
time derivative of the metric from the ADMBase timelevels) are a larger
rewrite whose priority I would like to discuss with the maintainers.

On the question of community interest and a published paper: the paper
describing the method and the verification is included in the
repository (doc/geodesic_paper.pdf). I plan to submit it to arXiv
(gr-qc, cross-listed with astro-ph.HE) once it has benefited from the
community's feedback, and subsequently to a journal, e.g. Classical and
Quantum Gravity. I hope this addresses the "current interest"
criterion in due course.

With this, I believe the thorn now meets the contribution page's
requirements on documentation, examples and self-tests, within its
stated scope. I would appreciate guidance on the next step, and on
whether the thorn could be considered for an "incoming" listing.

Best regards,

Yuhua Li

At 2026-09-09 22:18:59, "Steven R. Brandt" <sbrandt at cct.lsu.edu> wrote:

Sure, we can go ahead with email. However, you should probably be sending to users at einsteintoolkit.org to address the group. See:

The current working procedure for contributions is:

Author(s) contacts the Einstein Toolkit consortium (e.g. through the users or maintainers mail lists) about software that they intend to contribute
Discussions take place between the maintainers and author(s) to discuss issues above.

One question you need to address at some ponit: 

To focus development and support, optimize resources, and provide best practises, the Einstein Toolkit components should be of current interest to the community.
This is phrased ambiguously, but usually means there's a paper published in a reputable journal somewhere.

--Steve

On 9/9/2026 8:37 AM, Yuhua Li wrote:

Dear Steve,

Thank you for taking the time to look at the thorn and the paper, and for
forwarding the evaluation. I have gone through it carefully.

I agree with the two problems you singled out — the missing READS/WRITES
clauses and the MPI layout — and most of the other findings are also
correct. The evaluation gave me a clear roadmap, and I have now completed
the first, mechanical stage of the rework:

- schedule.ccl: geodesics_integrate now runs with OPTIONS: global and
  declares READS on the ADMBase metric; Geodesic_ParamCheck is actually
  scheduled at CCTK_PARAMCHECK;
- interface.ccl: the particle arrays are now DISTRIB=CONSTANT and
  checkpointable; the unused CoordGauge inherit is gone;
- param.ccl: the hard KerrSchild dependency was removed — the thorn has
  its own M and a parameters for the exact mode;
- storage now follows particle_n_total instead of particle_n;
- code fixes: the 4x4 metric inversion no longer returns a garbage inverse
  on singular pivots; the interpolation domain guard now matches the
  6th-order stencil; Cactus logging was moved out of the OpenMP loop;
  omp.h is guarded by _OPENMP; the parameter prose and the copyright
  headers are fixed;
- par/example.par now uses only public thorns and runs on a stock ET
  checkout; the README states the current limitations explicitly
  (single refinement level, unigrid, particle arrays replicated on every
  rank).

All of this is pushed to the repository, and the thorn rebuilds and runs
cleanly.

The remaining, architectural items — correct behaviour under MPI with
more than one rank, interpolation through CarpetInterp/AEILocalInterp, and
the time derivative of the metric from the ADMBase timelevels — are a
larger rewrite. I would like to discuss their priority with the
maintainers before starting, and I will state the current domain clearly
in the paper as well: unigrid, a single MPI process, stationary or slowly
evolving metrics.

For the ET contribution requirements I still plan to add the
doc/documentation.tex ThornGuide documentation and a test/ case
(conservation of E and Lz on a circular Kerr orbit) — a pointer to a good
example test to follow would be appreciated.

About the weekly meetings: I would honestly prefer not to join, because
my spoken English — especially listening — is not good enough for a live
discussion, and I cannot change that in the short term. I hope we can
communicate in writing instead, here on the mailing list or by email; if
a short written summary for one of the meetings would help, I am happy to
provide one.

Thank you again for the constructive feedback.

Best regards,

Yuhua Li

At 2026-09-09 07:07:21, "Steven R. Brandt" <sbrandt at cct.lsu.edu> wrote:

Yuhua,

I had Grok take a look at your thorn and paper. You will find the feedback attached (eval.md). At least some of the things it identifies are valid problems, namely the lack of READS/WRITES clauses in the schedule and MPI support.

You may want to consider joining one of the weekly ET meetings to make your case (I realize that the time will probably be challenging for you).

--Steve

On 9/8/2026 11:00 AM, Yuhua Li wrote:

Dear Steven,

Thank you for the quick and encouraging reply, and for the pointer to the
contribution process.

To answer your question directly: my goal is to have Geodesic included in
the Einstein Toolkit, and I am willing to follow the process described at
https://einsteintoolkit.org/contribute.html step by step. In the meantime,
I would be glad if the thorn could be added to the "Thorns we know of" 
list.

Where the thorn stands with respect to the requirements: 

 - Documentation: the repository has a README with purpose, build and usage
   instructions and a parameter table; the algorithms and the verification
   are described in the paper draft (doc/geodesic_paper.pdf). 
 - Examples: par/example.par is a complete, runnable example, and the par/ 
   directory contains the parameter files that reproduce every result
   reported in the paper. I am happy to add an automated test in the ET
   test-suite format — a pointer to a good example test to follow would be
   appreciated.
 - Licence: GPLv2+, included as COPYING.
 - Hosting: the code is on GitHub (https://github.com/wylyhzh/Geodesic).
   I am open to hosting it at einsteintoolkit.org if that is preferred.

Please let me know what the next step should be — for example, whether the
thorn can be placed into an "incoming" repository, and what the review
will look at first. I will respond to any requested changes in a timely
manner.

Best regards,

Yuhua Li 

At 2026-09-08 22:41:39, "Steven R. Brandt via Users" <users at einsteintoolkit.org> wrote:

Dear Yuhua,

Thank you for writing and for putting the code and the
paper draft in a public repository under GPLv2+. Independent
contributions of this kind are welcome, and a
test-particle geodesic tracker is something we don't have: the ET currently ships
fluid tracers (particle_tracerET) and puncture tracking
(PunctureTracker), but not a timelike geodesic integrator on the 3+1
metric.

Were you hoping to have it included in the ET, or were you just looking
to share the code with the community?  If so, we can help you with the process.
Please take a look at https://einsteintoolkit.org/contribute.html
if you haven't already.

If you would like to do something less formal, we can share
your link on our list of "thorns we know of":
https://docs.einsteintoolkit.org/et-docs/Thorns_we_know_of

Best regards,

Steven R. Brandt

On 9/8/2026 12:28 AM, Yuhua Li via Users wrote:

Dear Einstein Toolkit community,

I am a retired researcher (background in mathematics and computer science)
working independently from China. Over the past ten years I have been
building a test-particle geodesic tracker for the Einstein Toolkit, and I
would like to share it with the community.

The Geodesic thorn integrates geodesics for large numbers of test particles
in Kerr–Schild Cartesian coordinates. It supports (i) the exact Kerr–Schild
metric, independent of the grid (verified symbolically to be the vacuum
solution to machine precision), and (ii) 27-point local Lagrange
interpolation of the grid metric, so it also works for arbitrary spacetimes
carried on the grid (e.g., GRHydro evolutions). The per-particle integration
is fully independent and parallelized with OpenMP (validated with 10^4
particles).

The code (GPLv2+), the configuration files used in the validation runs, and a
paper draft describing the method and verification are all available in this
public repository: https://github.com/wylyhzh/Geodesic

I plan to submit the paper to arXiv (gr-qc, cross-list astro-ph.HE) once it
has benefited from the community's feedback.

I would appreciate: (1) feedback on whether the thorn meets ET
standards, and what would be needed to have it listed with the ET thorns;
(2) any comments on the paper. I am most comfortable discussing in
writing, so I would prefer to continue the conversation here on the
mailing list or by email, whichever is more convenient.

I am happy to provide any further information.

Best regards,

Yuhua Li

_______________________________________________
Users mailing list
Users at einsteintoolkit.orghttp://lists.einsteintoolkit.org/mailman/listinfo/users
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.einsteintoolkit.org/pipermail/users/attachments/20260910/62a9125e/attachment-0001.htm>