parthenon-hpc-lab · pdmullen · Mar 25, 2026 · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,7 @@
 ## Current develop
 
 ### Added (new features/APIs/variables/...)
+- [[PR 1391]](https://github.com/parthenon-hpc-lab/parthenon/pull/1391) Towards Curvilinear Swarms
 - [[PR 1408]](https://github.com/parthenon-hpc-lab/parthenon/pull/1408) Add GetAsUnresolvedString() method to ParameterInput
 - [[PR 1050]](https://github.com/parthenon-hpc-lab/parthenon/pull/1050) Add support for OpenPMD/ADIOS2 output (incl slices and coarsened dumps)
 - [[PR 1271]](https://github.com/parthenon-hpc-lab/parthenon/pull/1271) Add option to set a minimum number of teams for boundary communication kernels
@@ -51,6 +52,7 @@
 
 
 ### Incompatibilities (i.e. breaking changes)
+- [[PR 1391]](https://github.com/parthenon-hpc-lab/parthenon/pull/1391) Towards Curvilinear Swarms
 - [[PR 1385]](https://github.com/parthenon-hpc-lab/parthenon/pull/1385) ParameterInput internal storage refactor removes direct access to linked list (`pfirst_block`). Use `GetBlocksWithPrefix()` or `GetBlockNames()` instead.
 - [[PR 1351]](https://github.com/parthenon-hpc-lab/parthenon/pull/1351) Bump Kokkos 5 & C++20
 - [[PR 1377]](https://github.com/parthenon-hpc-lab/parthenon/pull/1377) Extend Initialization Hierarchy

diff --git a/doc/sphinx/src/particles.rst b/doc/sphinx/src/particles.rst
@@ -1,3 +1,5 @@
+.. This file was made in part with generative AI.
+
 Particles
 =========
 
@@ -11,8 +13,8 @@ Swarms
 
 A ``Swarm`` contains all the particle data for all particles of a given
 species. It owns a set of ``ParticleVariable``\ s, one for each value of
-each particle. For example, the spatial positions ``x``, ``y``, and
-``z`` of the particles in a swarm are three separate
+each particle. For example, the spatial positions ``x1``, ``x2``, and
+``x3`` of the particles in a swarm are three separate
 ``ParticleVariable``\ s. ``ParticleVariable``\ s can be either ``Real``-,
 ``uint64_t``-, or ``int``-valued, which is specified by the metadata values
 ``Metadata::Real``, ``MetaData::UInt64``, and ``Metadata::Integer``. ``ParticleVariable``\ s
@@ -21,7 +23,7 @@ should also contain the ``Metadata::Particle`` flag. By default,
 to 2D data per particle is currently supported, by passing
 ``std::vector<int>{N1, N2}`` as the second argument to the
 ``ParticleVariable`` ``Metadata``. All ``Swarm``\ s by default contain
-positional ``x``, ``y``, and ``z`` ``ParticleVariable``\ s and a ``uint64`` particle
+positional ``x1``, ``x2``, and ``x3`` ``ParticleVariable``\ s and a ``uint64`` particle
 ``id`` that is persistent and unique for a given simulation.
 The latter field can be disabled (e.g., because it is not required for a method
 that constant creates and destroys anonymous particles) by providing the
@@ -47,6 +49,13 @@ permit ``Swarm``s to be retrieved from ``"base"`` ``MeshBlockData`` and ``MeshDa
    particles that the reservation holds for a given swarm by calling
    ``metadata.SetInitialSwarmPoolReservation(nparticles);``.
 
+.. note::
+
+   Particle infrastructure now operates in the native ``x1``, ``x2``, and ``x3``
+   coordinate directions rather than assuming Cartesian ``x``, ``y``, and ``z``.
+   That said, particles and swarms in curvilinear coordinate systems remain mostly
+   untested.
+
 The ``Swarm`` is a host-side object, but some of its data members are
 required for device- side compution. To access this data, a
 ``SwarmDeviceContext`` object is created via
@@ -92,11 +101,11 @@ computations on currently active particles:
 
 .. code:: cpp
 
-   auto &x = swarm.Get("x").Get();
+   auto &x1 = swarm.Get(swarm_position::x1::name()).Get();
    swarm.pmy_block->par_for("Simple loop", 0, swarm.GetMaxActiveIndex(),
      KOKKOS_LAMBDA(const int n) {
        if (swarm_d.IsActive(n)) {
-         x(n) += 1.0;
+         x1(n) += 1.0;
        }
      });
 
@@ -177,14 +186,14 @@ Similar to grid variables, swarms can be packed over ``MeshBlock``\ s via ``Swar
 a ``SwarmPack`` via a ``std::vector<std::string>`` or the type-based variable prescription
 previously used by ``SparsePack``\ s (see :ref:`sparse_packs`).
 
-For packing via string (wherein below, ``swarm_position::x::name()`` returns a string),
+For packing via string (wherein below, ``swarm_position::x1::name()`` returns a string),
 one must specify the data type by template argument:
 
 .. code:: cpp
 
-   std::vector<std::string> vars{swarm_position::x::name(),
-                                 swarm_position::y::name(),
-                                 swarm_position::z::name()};
+   std::vector<std::string> vars{swarm_position::x1::name(),
+                                 swarm_position::x2::name(),
+                                 swarm_position::x3::name()};
    static auto desc = MakeSwarmPackDescriptor<Real>(swarm_name, vars);
    auto pack = desc.GetPack(md);
 
@@ -194,9 +203,9 @@ example), the type can be inferred automatically:
 
 .. code:: cpp
 
-   static auto desc = MakeSwarmPackDescriptor<swarm_position::x,
-                                              swarm_position::y,
-                                              swarm_position::z>(swarm_name);
+   static auto desc = MakeSwarmPackDescriptor<swarm_position::x1,
+                                              swarm_position::x2,
+                                              swarm_position::x3>(swarm_name);
    auto pack = desc.GetPack(md);
 
 

diff --git a/example/particle_leapfrog/particle_leapfrog.cpp b/example/particle_leapfrog/particle_leapfrog.cpp
@@ -183,9 +183,9 @@ void PostInitialization(MeshBlock *pmb, ParameterInput *pin) {
   auto new_particles_context = swarm->AddEmptyParticles(num_particles_this_block);
 
   auto &id = swarm->Get<std::uint64_t>(swarm_position::id::name()).Get();
-  auto &x = swarm->Get<Real>(swarm_position::x::name()).Get();
-  auto &y = swarm->Get<Real>(swarm_position::y::name()).Get();
-  auto &z = swarm->Get<Real>(swarm_position::z::name()).Get();
+  auto &x = swarm->Get<Real>(swarm_position::x1::name()).Get();
+  auto &y = swarm->Get<Real>(swarm_position::x2::name()).Get();
+  auto &z = swarm->Get<Real>(swarm_position::x3::name()).Get();
   auto &v = swarm->Get<Real>("v").Get();
   auto &vv = swarm->Get<Real>("vv").Get();
 
@@ -225,7 +225,7 @@ TaskStatus TransportParticles(MeshData<Real> *md, const StagedIntegrator *integr
   // NOTE(@pdmullen): the data type for Positions (Real) are automatically deduced from
   // the variable typing
   static auto desc_pos =
-      MakeSwarmPackDescriptor<swarm_position::x, swarm_position::y, swarm_position::z>(
+      MakeSwarmPackDescriptor<swarm_position::x1, swarm_position::x2, swarm_position::x3>(
           swarm_name);
   auto pack_pos = desc_pos.GetPack(md);
 
@@ -250,19 +250,19 @@ TaskStatus TransportParticles(MeshData<Real> *md, const StagedIntegrator *integr
         const auto swarm_d = pack_pos.GetContext(b);
         if (swarm_d.IsActive(n)) {
           // drift
-          pack_pos(b, swarm_position::x(), n) += pack_v(b, iv + 0, n) * 0.5 * dt;
-          pack_pos(b, swarm_position::y(), n) += pack_v(b, iv + 1, n) * 0.5 * dt;
-          pack_pos(b, swarm_position::z(), n) += pack_v(b, iv + 2, n) * 0.5 * dt;
+          pack_pos(b, swarm_position::x1(), n) += pack_v(b, iv + 0, n) * 0.5 * dt;
+          pack_pos(b, swarm_position::x2(), n) += pack_v(b, iv + 1, n) * 0.5 * dt;
+          pack_pos(b, swarm_position::x3(), n) += pack_v(b, iv + 2, n) * 0.5 * dt;
 
           // kick
           pack_v(b, iv + 0, n) += ax * dt;
           pack_v(b, iv + 1, n) += ay * dt;
           pack_v(b, iv + 2, n) += az * dt;
 
           // drift
-          pack_pos(b, swarm_position::x(), n) += pack_v(b, iv + 0, n) * 0.5 * dt;
-          pack_pos(b, swarm_position::y(), n) += pack_v(b, iv + 1, n) * 0.5 * dt;
-          pack_pos(b, swarm_position::z(), n) += pack_v(b, iv + 2, n) * 0.5 * dt;
+          pack_pos(b, swarm_position::x1(), n) += pack_v(b, iv + 0, n) * 0.5 * dt;
+          pack_pos(b, swarm_position::x2(), n) += pack_v(b, iv + 1, n) * 0.5 * dt;
+          pack_pos(b, swarm_position::x3(), n) += pack_v(b, iv + 2, n) * 0.5 * dt;
 
           // id
           PARTHENON_REQUIRE(pack_id(b, swarm_position::id(), n) >= 0,

diff --git a/example/particle_tracers/particle_tracers.cpp b/example/particle_tracers/particle_tracers.cpp
@@ -284,7 +284,7 @@ void SourceTracers(MeshBlock *pmb, ParameterInput *pin) {
 
   // Create pack
   static auto desc =
-      MakeSwarmPackDescriptor<swarm_position::x, swarm_position::y, swarm_position::z>(
+      MakeSwarmPackDescriptor<swarm_position::x1, swarm_position::x2, swarm_position::x3>(
           swarm_name);
   auto pack = desc.GetPack(mbd.get());
 
@@ -296,9 +296,9 @@ void SourceTracers(MeshBlock *pmb, ParameterInput *pin) {
         auto rng_gen = rng_pool.get_state();
 
         // Extract particle position
-        Real &xx = pack(0, swarm_position::x(), n);
-        Real &yy = pack(0, swarm_position::y(), n);
-        Real &zz = pack(0, swarm_position::z(), n);
+        Real &xx = pack(0, swarm_position::x1(), n);
+        Real &yy = pack(0, swarm_position::x2(), n);
+        Real &zz = pack(0, swarm_position::x3(), n);
 
         // Rejection sample the x position
         Real val;
@@ -334,7 +334,7 @@ TaskStatus AdvectTracers(MeshData<Real> *md, const Real dt) {
 
   // Create pack
   static auto desc =
-      MakeSwarmPackDescriptor<swarm_position::x, swarm_position::y, swarm_position::z>(
+      MakeSwarmPackDescriptor<swarm_position::x1, swarm_position::x2, swarm_position::x3>(
           swarm_name);
   auto pack = desc.GetPack(md);
 
@@ -345,9 +345,9 @@ TaskStatus AdvectTracers(MeshData<Real> *md, const Real dt) {
         auto [b, n] = pack.GetBlockParticleIndices(idx);
         const auto &swarm_d = pack.GetContext(b);
         if (swarm_d.IsActive(n)) {
-          pack(b, swarm_position::x(), n) += vx * dt;
-          pack(b, swarm_position::y(), n) += vy * dt;
-          pack(b, swarm_position::z(), n) += vz * dt;
+          pack(b, swarm_position::x1(), n) += vx * dt;
+          pack(b, swarm_position::x2(), n) += vy * dt;
+          pack(b, swarm_position::x3(), n) += vz * dt;
         }
       });
 
@@ -366,7 +366,7 @@ TaskStatus DepositTracers(MeshData<Real> *md) {
   // Create packs
   static auto desc = MakePackDescriptor<field::deposition>(resolved_pkgs.get());
   static auto pdesc =
-      MakeSwarmPackDescriptor<swarm_position::x, swarm_position::y, swarm_position::z>(
+      MakeSwarmPackDescriptor<swarm_position::x1, swarm_position::x2, swarm_position::x3>(
           swarm_name);
   auto vmesh = desc.GetPack(md);
   auto vpart = pdesc.GetPack(md);
@@ -387,9 +387,9 @@ TaskStatus DepositTracers(MeshData<Real> *md) {
         const auto &swarm_d = vpart.GetContext(b);
         if (swarm_d.IsActive(n)) {
           int ip, jp, kp;
-          const Real &xx = vpart(b, swarm_position::x(), n);
-          const Real &yy = vpart(b, swarm_position::y(), n);
-          const Real &zz = vpart(b, swarm_position::z(), n);
+          const Real &xx = vpart(b, swarm_position::x1(), n);
+          const Real &yy = vpart(b, swarm_position::x2(), n);
+          const Real &zz = vpart(b, swarm_position::x3(), n);
           swarm_d.Xtoijk(xx, yy, zz, ip, jp, kp);
 
           // For testing in this example we make sure the indices are correct; these

diff --git a/example/particles/particles.cpp b/example/particles/particles.cpp
@@ -1,5 +1,5 @@
 //========================================================================================
-// (C) (or copyright) 2020-2024. Triad National Security, LLC. All rights reserved.
+// (C) (or copyright) 2020-2026. Triad National Security, LLC. All rights reserved.
 //
 // This program was produced under U.S. Government contract 89233218CNA000001 for Los
 // Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC
@@ -11,6 +11,8 @@
 // the public, perform publicly and display publicly, and to permit others to do so.
 //========================================================================================
 
+// This file was made in part with generative AI.
+
 #include <algorithm>
 #include <limits>
 #include <memory>
@@ -183,9 +185,9 @@ TaskStatus DepositParticles(MeshBlock *pmb) {
   const Real &minx_j = pmb->coords.Xf<2>(jb.s);
   const Real &minx_k = pmb->coords.Xf<3>(kb.s);
 
-  const auto &x = swarm->Get<Real>(swarm_position::x::name()).Get();
-  const auto &y = swarm->Get<Real>(swarm_position::y::name()).Get();
-  const auto &z = swarm->Get<Real>(swarm_position::z::name()).Get();
+  const auto &x = swarm->Get<Real>(swarm_position::x1::name()).Get();
+  const auto &y = swarm->Get<Real>(swarm_position::x2::name()).Get();
+  const auto &z = swarm->Get<Real>(swarm_position::x3::name()).Get();
   const auto &weight = swarm->Get<Real>("weight").Get();
   auto swarm_d = swarm->GetDeviceContext();
 
@@ -262,9 +264,9 @@ TaskStatus CreateSomeParticles(MeshBlock *pmb, const double t0) {
   const Real &minx_k = pmb->coords.Xf<3>(kb.s);
 
   auto &t = swarm->Get<Real>("t").Get();
-  auto &x = swarm->Get<Real>(swarm_position::x::name()).Get();
-  auto &y = swarm->Get<Real>(swarm_position::y::name()).Get();
-  auto &z = swarm->Get<Real>(swarm_position::z::name()).Get();
+  auto &x = swarm->Get<Real>(swarm_position::x1::name()).Get();
+  auto &y = swarm->Get<Real>(swarm_position::x2::name()).Get();
+  auto &z = swarm->Get<Real>(swarm_position::x3::name()).Get();
   auto &v = swarm->Get<Real>("v").Get();
   auto &weight = swarm->Get<Real>("weight").Get();
 
@@ -373,9 +375,9 @@ TaskStatus TransportParticles(MeshBlock *pmb, const double t0, const double dt)
   int max_active_index = swarm->GetMaxActiveIndex();
 
   auto &t = swarm->Get<Real>("t").Get();
-  auto &x = swarm->Get<Real>(swarm_position::x::name()).Get();
-  auto &y = swarm->Get<Real>(swarm_position::y::name()).Get();
-  auto &z = swarm->Get<Real>(swarm_position::z::name()).Get();
+  auto &x = swarm->Get<Real>(swarm_position::x1::name()).Get();
+  auto &y = swarm->Get<Real>(swarm_position::x2::name()).Get();
+  auto &z = swarm->Get<Real>(swarm_position::x3::name()).Get();
   auto &v = swarm->Get<Real>("v").Get();
 
   const Real &dx_i = pmb->coords.Dxf<1>(pmb->cellbounds.is(IndexDomain::interior));

diff --git a/scripts/python/packages/parthenon_tools/parthenon_tools/movie2d.py b/scripts/python/packages/parthenon_tools/parthenon_tools/movie2d.py
@@ -4,7 +4,7 @@
 # Copyright(C) 2020-2025 The Parthenon collaboration
 # Licensed under the 3-clause BSD License, see LICENSE file for details
 # =========================================================================================
-# (C) (or copyright) 2020-2025. Triad National Security, LLC. All rights reserved.
+# (C) (or copyright) 2020-2026. Triad National Security, LLC. All rights reserved.
 #
 # This program was produced under U.S. Government contract 89233218CNA000001 for Los
 # Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC
@@ -16,6 +16,8 @@
 # the public, perform publicly and display publicly, and to permit others to do so.
 # =========================================================================================
 
+# This file was made in part with generative AI.
+
 from __future__ import print_function
 
 import re
@@ -450,8 +452,8 @@ def main():
                     ERROR_FLAG = True
                     break
                 swarm = data.GetSwarm(args.swarm)
-                swarmx = subsample(swarm.x, args.maxparticles)
-                swarmy = subsample(swarm.y, args.maxparticles)
+                swarmx = subsample(swarm.x1, args.maxparticles)
+                swarmy = subsample(swarm.x2, args.maxparticles)
                 if args.swarmcolor is not None:
                     if not is_color_like(args.swarmcolor):
                         if args.swarmcolor not in swarm.variables:

diff --git a/scripts/python/packages/parthenon_tools/parthenon_tools/phdf.py b/scripts/python/packages/parthenon_tools/parthenon_tools/phdf.py
@@ -3,7 +3,7 @@
 # Copyright(C) 2020-2024 The Parthenon collaboration
 # Licensed under the 3-clause BSD License, see LICENSE file for details
 # =========================================================================================
-# (C) (or copyright) 2020-2024. Triad National Security, LLC. All rights reserved.
+# (C) (or copyright) 2020-2026. Triad National Security, LLC. All rights reserved.
 #
 # This program was produced under U.S. Government contract 89233218CNA000001 for Los
 # Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC
@@ -15,6 +15,8 @@
 # the public, perform publicly and display publicly, and to permit others to do so.
 # =========================================================================================
 
+# This file was made in part with generative AI.
+
 from __future__ import print_function
 import h5py as h
 import os, sys, errno
@@ -27,7 +29,8 @@ class Swarm:
           name: The name of the swarm
           variables: The variables in available in the swarm.
           varData: The swarm variables. Greedily accessed.
-          x, y, z: The x, y, and z positions of the swarm
+          x, y, z: Legacy position accessors
+          x1, x2, x3: Position accessors in native mesh coordinates
     """
 
     def __init__(self, fid, swarmname):
@@ -43,16 +46,28 @@ def Block(self, b):
         """Returns a Python slice for the particles only on block b"""
         return slice(self.offsets[b], self.offsets[b] + self.counts[b] + 1)
 
+    def _get_exact(self, variable):
+        if variable not in self.varData:
+            self.varData[variable] = self.gid[variable][:]
+        return self.varData[variable]
+
+    def _get_compat(self, variables):
+        for variable in variables:
+            try:
+                return self._get_exact(variable)
+            except KeyError:
+                pass
+        print(f"ERROR: none of {variables} found in {self.name}")
+        return None
+
     def Get(self, variable):
         """Reads data for the named swarm var from file and caches it in the
         dictionary. Returns None if variable is not found in the file
         or data. Data is always of shape:
         [tensor indices, particle index]
         """
         try:
-            if self.varData.get(variable) is None:
-                self.varData[variable] = self.gid[variable][:]
-            return self.varData[variable]
+            return self._get_exact(variable)
         except KeyError:
             print(f"ERROR: {variable} not found in {self.name}")
             return None
@@ -63,15 +78,27 @@ def id(self):
 
     @property
     def x(self):
-        return self.Get("swarm.x")
+        return self._get_compat(("swarm.x", "swarm.x1"))
 
     @property
     def y(self):
-        return self.Get("swarm.y")
+        return self._get_compat(("swarm.y", "swarm.x2"))
 
     @property
     def z(self):
-        return self.Get("swarm.z")
+        return self._get_compat(("swarm.z", "swarm.x3"))
+
+    @property
+    def x1(self):
+        return self._get_compat(("swarm.x1", "swarm.x"))
+
+    @property
+    def x2(self):
+        return self._get_compat(("swarm.x2", "swarm.y"))
+
+    @property
+    def x3(self):
+        return self._get_compat(("swarm.x3", "swarm.z"))
 
     def __getitem__(self, key):
         return self.Get(key)