Add Self-Gravity

doc/src/physics.rst

@@ -10,7 +10,7 @@
 .. license in this material to reproduce, prepare derivative works, distribute copies to
 .. the public, perform publicly and display publicly, and to permit others to do so.
 .. =======================================================================================
-
+.. This file was created in part or in whole by one of OpenAI's generative AI models
 .. _physics:
 
 Physics Modules
@@ -28,6 +28,7 @@ In general, to activate a physics capability, it must be set in the ``<physics>`
    conduction = false
    cooling = false
    gravity = false
+   self_gravity = false
    nbody = false
    rotating_frame = false
    radiation = false
@@ -750,6 +751,46 @@ Available options are:
 
 See `N-Body Dynamics`_ for a description of how to set up the N-body system.
 
+Self Gravity
+------------
+
+The ``<self_gravity>`` node enables self-consistent gravitational forces for fluid components by solving the Poisson equation
+
+.. math::
+
+   \nabla^2 \phi = 4 \pi G \rho_{\mathrm{total}},
+
+where :math:`\rho_{\mathrm{total}}` is the sum of the mass densities of all fluids and :math:`G` is the gravitational constant in code units. The right-hand side is assembled from all registered fluid densities, and the gravitational potential :math:`\phi` is then used to compute gravitational forces in the hydrodynamic update.
+
+The self-gravity module currently supports Cartesian geometries only.
+
+The parameter stored internally is ``four_pi_G = 4 \pi G``. By default, :math:`G` is taken from the code constants and converted to code units. This behavior can be overridden by setting
+
+.. code-block:: ini
+
+   <self_gravity>
+   units_override = true
+   four_pi_G = 1.0
+
+When ``units_override`` is enabled, the supplied value of ``four_pi_G`` is used instead of the value derived from the code constants.
+
+The gravitational potential currently supports periodic and zero (Dirichlet) boundary conditions. For fully periodic domains, the Poisson equation is solvable only if the mean density is removed. This is handled using the Jeans swindle, which subtracts the domain-averaged density before solving. If all mesh boundaries are periodic, ``use_swindle`` is automatically required and the code will abort if it is disabled. If ``use_swindle`` is enabled in a configuration that is not fully periodic, a warning is issued.
+
+Zero Dirichlet boundary conditions for :math:`\phi` may be specified per face in the ``<self_gravity>`` block, e.g.,
+
+.. code-block:: ini
+
+   <self_gravity>
+   ix1_bc = zero
+   ox1_bc = zero
+
+Only faces explicitly set to ``zero`` enroll a zero-potential boundary function; otherwise, the mesh-level boundary configuration (e.g., periodic) applies.
+
+The self-gravity package provides two primary fields: the gravitational potential ``grav::phi`` and the Poisson right-hand side ``grav::rhs``.  ``grav::rhs`` corresponds to :math:`4 \pi G \sum_i \rho_i` and is constructed in the package’s ``FillDerivedMesh`` routine, including application of the Jeans swindle when enabled.
+
+The Poisson equation is registered through Parthenon’s linear solver framework. The solver consists of a BiCGSTAB Krylov method preconditioned by a multigrid (MG) solver.
+
+
 Rotating Frame
 --------------
 

inputs/self-gravity/poly.in

@@ -0,0 +1,102 @@
+# ========================================================================================
+#  (C) (or copyright) 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
+#  for the U.S. Department of Energy/National Nuclear Security Administration. All rights
+#  in the program are reserved by Triad National Security, LLC, and the U.S. Department
+#  of Energy/National Nuclear Security Administration. The Government is granted for
+#  itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide
+#  license in this material to reproduce, prepare derivative works, distribute copies to
+#  the public, perform publicly and display publicly, and to permit others to do so.
+# ========================================================================================
+
+<artemis>
+problem = polytrope      # name of the pgen
+coordinates = cartesian  # coordinate system
+
+<parthenon/job>
+problem_id = polytrope  # problem ID: basename of output filenames
+
+<parthenon/output1>
+file_type = hdf5  # HDF5 data dump
+variables = gas.prim.density, &
+            gas.prim.velocity, &
+            gas.prim.pressure, &
+            grav.phi, &
+            grav.rhs
+dt        = 1.0   # time increment between outputs
+
+<parthenon/output2>
+file_type = hst   # HDF5 data dump
+dt        = 1.0   # time increment between outputs
+
+<parthenon/time>
+nlim       = -1     # cycle limit
+tlim       = 100.0  # time limit (to be reset by problem generator)
+integrator = rk2    # time integration algorithm
+ncycle_out = 1      # interval for stdout summary info
+
+<parthenon/mesh>
+# do_coalesced_comms = true
+refinement = adaptive
+numlevel = 3
+multigrid = true
+
+nx1 = 64
+x1min = -32.0
+x1max = 32.0
+ix1_bc = outflow
+ox1_bc = outflow
+
+nx2 = 64
+x2min = -32.0
+x2max = 32.0
+ix2_bc = outflow
+ox2_bc = outflow
+
+nx3 = 64
+x3min = -32.0
+x3max = 32.0
+ix3_bc = outflow
+ox3_bc = outflow
+
+<parthenon/meshblock>
+nx1 = 16
+nx2 = 16
+nx3 = 16
+
+<parthenon/refinement0>
+method = magnitude
+comparator = greater_than
+field = gas.prim.density_0
+refine_tol = 0.1
+derefine_tol = 0.1
+
+<physics>
+gas = true
+self_gravity = true
+
+<gas>
+cfl = 0.9
+reconstruct = plm
+riemann = hllc-gamma
+
+<gas/eos/ideal>
+gamma = 2.0
+
+<self_gravity>
+print_per_step = true
+max_iterations = 100
+residual_tolerance = 1.0e-6
+units_override = true
+use_swindle = false
+ix1_bc = zero
+ox1_bc = zero
+ix2_bc = zero
+ox2_bc = zero
+ix3_bc = zero
+ox3_bc = zero
+
+<problem>
+iprob = 2

src/CMakeLists.txt

@@ -1,5 +1,5 @@
 # ========================================================================================
-#  (C) (or copyright) 2023-2025. Triad National Security, LLC. All rights reserved.
+#  (C) (or copyright) 2023-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
@@ -43,10 +43,10 @@ set (SRC_LIST
 
   gravity/binary_mass.cpp
   gravity/gravity.cpp
+  gravity/gravity.hpp
   gravity/nbody_gravity.hpp
   gravity/point_mass.cpp
   gravity/uniform.cpp
-  gravity/gravity.hpp
 
   nbody/nbody.cpp
   nbody/nbody.hpp
@@ -68,6 +68,7 @@ set (SRC_LIST
   pgen/kh.hpp
   pgen/linear_wave.hpp
   pgen/lw.hpp
+  pgen/polytrope.hpp
   pgen/pgen.hpp
   pgen/problem_modifier.hpp
   pgen/rt.hpp
@@ -91,6 +92,12 @@ set (SRC_LIST
   rotating_frame/rotating_frame_impl.hpp
   rotating_frame/rotating_frame.hpp
 
+  self_gravity/self_gravity.cpp
+  self_gravity/self_gravity.hpp
+  self_gravity/poisson_driver.cpp
+  self_gravity/poisson_equation.hpp
+  self_gravity/self_gravity.cpp
+
   utils/artemis_utils.cpp
   utils/artemis_utils.hpp
   utils/history.hpp

src/artemis.cpp

@@ -1,5 +1,5 @@
 //========================================================================================
-// (C) (or copyright) 2023-2025. Triad National Security, LLC. All rights reserved.
+// (C) (or copyright) 2023-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
@@ -26,6 +26,7 @@
 #include "radiation/radiation.hpp"
 #include "radiation/raytrace/raytrace.hpp"
 #include "rotating_frame/rotating_frame.hpp"
+#include "self_gravity/self_gravity.hpp"
 #include "utils/artemis_utils.hpp"
 #include "utils/history.hpp"
 #include "utils/units.hpp"
@@ -91,6 +92,7 @@ Packages_t ProcessPackages(std::unique_ptr<ParameterInput> &pin) {
   const bool do_gas = pin->GetOrAddBoolean("physics", "gas", true);
   const bool do_dust = pin->GetOrAddBoolean("physics", "dust", false);
   const bool do_gravity = pin->GetOrAddBoolean("physics", "gravity", false);
+  const bool do_self_gravity = pin->GetOrAddBoolean("physics", "self_gravity", false);
   const bool do_nbody = pin->GetOrAddBoolean("physics", "nbody", false);
   const bool do_rotating_frame = pin->GetOrAddBoolean("physics", "rotating_frame", false);
   const bool do_cooling = pin->GetOrAddBoolean("physics", "cooling", false);
@@ -128,6 +130,7 @@ Packages_t ProcessPackages(std::unique_ptr<ParameterInput> &pin) {
   artemis->AddParam("do_gas", do_gas);
   artemis->AddParam("do_dust", do_dust);
   artemis->AddParam("do_gravity", do_gravity);
+  artemis->AddParam("do_self_gravity", do_self_gravity);
   artemis->AddParam("do_nbody", do_nbody);
   artemis->AddParam("do_rotating_frame", do_rotating_frame);
   artemis->AddParam("do_cooling", do_cooling);
@@ -162,6 +165,8 @@ Packages_t ProcessPackages(std::unique_ptr<ParameterInput> &pin) {
   packages.Add(geometry::Initialize(pin.get()));
   if (do_nbody) packages.Add(NBody::Initialize(pin.get(), constants));
   if (do_gravity) packages.Add(Gravity::Initialize(pin.get(), constants, packages));
+  if (do_self_gravity)
+    packages.Add(SelfGravity::Initialize(pin.get(), constants, packages));
   if (do_gas) packages.Add(Gas::Initialize(pin.get(), units, constants, packages));
   if (do_dust) packages.Add(Dust::Initialize(pin.get(), units));
   if (do_rotating_frame) packages.Add(RotatingFrame::Initialize(pin.get()));

src/artemis.hpp

@@ -1,5 +1,5 @@
 //========================================================================================
-// (C) (or copyright) 2023-2025. Triad National Security, LLC. All rights reserved.
+// (C) (or copyright) 2023-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
@@ -97,6 +97,11 @@ SWARM_VARIABLE(int, rad.star, ijk);
 } // namespace star
 } // namespace rad
 
+namespace grav {
+ARTEMIS_VARIABLE(grav, phi);
+ARTEMIS_VARIABLE(grav, rhs);
+} // namespace grav
+
 namespace geom {
 ARTEMIS_VARIABLE(geom, x1v);
 ARTEMIS_VARIABLE(geom, x2v);

src/artemis_driver.cpp

@@ -1,5 +1,5 @@
 //========================================================================================
-// (C) (or copyright) 2023-2025. Triad National Security, LLC. All rights reserved.
+// (C) (or copyright) 2023-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
@@ -32,6 +32,7 @@
 #include "radiation/moments/moments.hpp"
 #include "radiation/raytrace/raytrace.hpp"
 #include "rotating_frame/rotating_frame.hpp"
+#include "self_gravity/self_gravity.hpp"
 #include "utils/integrators/artemis_integrator.hpp"
 
 using namespace parthenon::driver::prelude;
@@ -61,6 +62,7 @@ ArtemisDriver<GEOM>::ArtemisDriver(ParameterInput *pin, ApplicationInput *app_in
   do_gas = artemis_pkg->template Param<bool>("do_gas");
   do_dust = artemis_pkg->template Param<bool>("do_dust");
   do_gravity = artemis_pkg->template Param<bool>("do_gravity");
+  do_self_gravity = artemis_pkg->template Param<bool>("do_self_gravity");
   do_rotating_frame = artemis_pkg->template Param<bool>("do_rotating_frame");
   do_shear = artemis_pkg->template Param<bool>("do_shear");
   do_cooling = artemis_pkg->template Param<bool>("do_cooling");
@@ -235,6 +237,9 @@ TaskCollection ArtemisDriver<GEOM>::StepTasks() {
     const Real g1 = integrator->gam1[stage - 1];
     const Real bdt = integrator->beta[stage - 1] * integrator->dt;
 
+    // Compute gravitational potential
+    if (do_self_gravity) SelfGravity::SolvePoisson(tc, pmesh);
+
     TaskRegion &tr = tc.AddRegion(num_partitions);
     for (int i = 0; i < num_partitions; i++) {
       auto &tl = tr[i];
@@ -294,10 +299,17 @@ TaskCollection ArtemisDriver<GEOM>::StepTasks() {
                                  Gravity::ExternalGravity<GEOM>, u0.get(), time, bdt);
       }
 
-      TaskID rt_src = gravity_src;
+      // Apply self-gravity source term
+      TaskID self_gravity_src = gravity_src;
+      if (do_self_gravity) {
+        self_gravity_src =
+            tl.AddTask(gravity_src, SelfGravity::SelfGravity<GEOM>, u0.get(), time, bdt);
+      }
+
+      TaskID rt_src = self_gravity_src;
       // Note that radiation moments will handle this source term if active
       if (do_raytrace && !do_moment) {
-        rt_src = tl.AddTask(gravity_src, Gas::DepositEnergy, u0.get(), bdt);
+        rt_src = tl.AddTask(self_gravity_src, Gas::DepositEnergy, u0.get(), bdt);
       }
 
       // Apply rotating frame source term

src/artemis_driver.hpp

@@ -1,5 +1,5 @@
 //========================================================================================
-// (C) (or copyright) 2023-2025. Triad National Security, LLC. All rights reserved.
+// (C) (or copyright) 2023-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
@@ -53,7 +53,7 @@ class ArtemisDriver : public EvolutionDriver {
   IntegratorPtr_t integrator, nbody_integrator, rad_integrator;
   StateDescriptor *artemis_pkg;
   bool do_gas, do_dust, do_moment, do_imc;
-  bool do_gravity, do_nbody, do_rotating_frame, do_shear;
+  bool do_gravity, do_self_gravity, do_nbody, do_rotating_frame, do_shear;
   bool do_cooling, do_drag, do_viscosity, do_conduction, do_diffusion;
   bool do_coagulation, do_raytrace;
   bool update_fluxes;

src/artemis_params.yaml

@@ -78,6 +78,10 @@ physics:
     _type: "bool"
     _default: "false"
     _description: "Turn on gravity"
+  self_gravity:
+    _type: "bool"
+    _default: "false"
+    _description: "Turn on self-gravity"
   rotating_frame:
     _type: "bool"
     _default: "false"

src/pgen/beam.hpp

@@ -126,7 +126,6 @@ inline void BeamInnerX2(std::shared_ptr<MeshBlockData<Real>> &mbd, bool coarse)
   using parthenon::MakePackDescriptor;
   using TE = parthenon::TopologicalElement;
   auto pmb = mbd->GetBlockPointer();
-  if (coarse && !ArtemisUtils::CoarseNeighbor(pmb)) return;
 
   // Extract artemis package and params
   auto artemis_pkg = pmb->packages.Get("artemis");
@@ -204,7 +203,6 @@ inline void BeamInnerX1(std::shared_ptr<MeshBlockData<Real>> &mbd, bool coarse)
   using parthenon::MakePackDescriptor;
   using TE = parthenon::TopologicalElement;
   auto pmb = mbd->GetBlockPointer();
-  if (coarse && !ArtemisUtils::CoarseNeighbor(pmb)) return;
 
   // Extract artemis package and params
   auto artemis_pkg = pmb->packages.Get("artemis");

src/pgen/conduction.hpp

@@ -133,7 +133,6 @@ template <Coordinates GEOM, IndexDomain BDY, Diffusion::DiffType DTYP>
 void CondBoundaryImpl(std::shared_ptr<MeshBlockData<Real>> &mbd, bool coarse) {
   PARTHENON_INSTRUMENT
   auto pmb = mbd->GetBlockPointer();
-  if (coarse && !ArtemisUtils::CoarseNeighbor(pmb)) return;
 
   // Artemis package and params
   auto artemis_pkg = pmb->packages.Get("artemis");
@@ -267,7 +266,6 @@ template <Coordinates GEOM, IndexDomain BDY>
 inline void CondBoundary(std::shared_ptr<MeshBlockData<Real>> &mbd, bool coarse) {
   PARTHENON_INSTRUMENT
   auto pmb = mbd->GetBlockPointer();
-  if (coarse && !ArtemisUtils::CoarseNeighbor(pmb)) return;
 
   auto artemis_pkg = pmb->packages.Get("artemis");
   auto &pkg = pmb->packages.Get("gas");