MLMG: Expose Solver Parameters

docs/source/usage/parameters.rst

@@ -625,6 +625,29 @@ Numerics and algorithms
     This is in-development.
     At the moment, this flag only activates coordinate transformations and charge deposition.
 
+* ``algo.mlmg_relative_tolerance`` (``float``, optional, default: ``1.e-7``)
+    The relative precision with which the electrostatic space-charge fields should be calculated.
+    More specifically, the space-charge fields are computed with an iterative Multi-Level Multi-Grid (MLMG) solver.
+    This solver can fail to reach the default precision within a reasonable time.
+
+* ``algo.mlmg_absolute_tolerance`` (``float``, optional, default: ``0``, which means: ignored)
+    The absolute tolerance with which the space-charge fields should be calculated in units of V/m^2.
+    More specifically, the acceptable residual with which the solution can be considered converged.
+    In general this should be left as the default, but in cases where the simulation state changes very
+    little between steps it can occur that the initial guess for the MLMG solver is so close to the
+    converged value that it fails to improve that solution sufficiently to reach the
+    mlmg_relative_tolerance value."
+
+* ``algo.mlmg_max_iters`` (``integer``, optional, default: ``100``)
+    Maximum number of iterations used for MLMG solver for space-charge fields calculation.
+    In case if MLMG converges but fails to reach the desired self_fields_required_precision,
+    this parameter may be increased.
+
+* ``algo.mlmg_verbosity`` (``integer``, optional, default: ``1``)
+    The verbosity used for MLMG solver for space-charge fields calculation.
+    Currently MLMG solver looks for verbosity levels from 0-5.
+    A higher number results in more verbose output.
+
 .. _running-cpp-parameters-diagnostics:
 
 Diagnostics and output

docs/source/usage/python.rst

@@ -66,6 +66,39 @@ General
       This is in-development.
       At the moment, this flag only activates coordinate transformations and charge deposition.
 
+   .. py:property:: mlmg_relative_tolerance
+
+      Default: ``1.e-7``
+
+      The relative precision with which the electrostatic space-charge fields should be calculated.
+      More specifically, the space-charge fields are computed with an iterative Multi-Level Multi-Grid (MLMG) solver.
+      This solver can fail to reach the default precision within a reasonable time.
+
+   .. py:property:: mlmg_absolute_tolerance
+
+      Default: ``0``, which means: ignored
+
+      The absolute tolerance with which the space-charge fields should be calculated in units of :math:`V/m^2`.
+      More specifically, the acceptable residual with which the solution can be considered converged.
+      In general this should be left as the default, but in cases where the simulation state changes very
+      little between steps it can occur that the initial guess for the MLMG solver is so close to the
+      converged value that it fails to improve that solution sufficiently to reach the ``mlmg_relative_tolerance`` value.
+
+   .. py:property:: mlmg_max_iters
+
+      Default: ``100``
+
+      Maximum number of iterations used for MLMG solver for space-charge fields calculation.
+      In case if MLMG converges but fails to reach the desired self_fields_required_precision, this parameter may be increased.
+
+   .. py:property:: mlmg_verbosity
+
+      Default: ``1``
+
+      The verbosity used for MLMG solver for space-charge fields calculation.
+      Currently MLMG solver looks for verbosity levels from 0-5.
+      A higher number results in more verbose output.
+
    .. py:property:: diagnostics
 
       Enable (``True``) or disable (``False``) diagnostics generally (default: ``True``).

src/ImpactX.cpp

@@ -22,6 +22,7 @@
 #include <AMReX.H>
 #include <AMReX_AmrParGDB.H>
 #include <AMReX_BLProfiler.H>
+#include <AMReX_ParmParse.H>
 #include <AMReX_Print.H>
 #include <AMReX_Utility.H>
 

src/particles/spacecharge/PoissonSolve.cpp

@@ -15,6 +15,7 @@
 #include <AMReX_BLProfiler.H>
 #include <AMReX_Extension.H>  // for AMREX_RESTRICT
 #include <AMReX_LO_BCTYPES.H>
+#include <AMReX_ParmParse.H>
 #include <AMReX_REAL.H>       // for ParticleReal
 
 #include <cmath>
@@ -50,11 +51,16 @@ namespace impactx::spacecharge
         // particle.
         std::array<amrex::Real, 3> const beta_xyz = {0.0, 0.0, beta_s};
 
-        amrex::Real const mlmg_relative_tolerance = 1.e-7; // relative TODO: make smaller for SP
-        amrex::Real const mlmg_absolute_tolerance = 0.0;   // ignored
+        amrex::ParmParse pp_algo("algo");
+        amrex::Real mlmg_relative_tolerance = 1.e-7; // relative TODO: make smaller for SP
+        amrex::Real mlmg_absolute_tolerance = 0.0;   // ignored
+        pp_algo.queryAdd("mlmg_relative_tolerance", mlmg_relative_tolerance);
+        pp_algo.queryAdd("mlmg_absolute_tolerance", mlmg_absolute_tolerance);
 
-        int const mlmg_max_iters = 100;
-        int const mlmg_verbosity = 1;
+        int mlmg_max_iters = 100;
+        int mlmg_verbosity = 1;
+        pp_algo.queryAdd("mlmg_max_iters", mlmg_max_iters);
+        pp_algo.queryAdd("mlmg_verbosity", mlmg_verbosity);
 
         struct PoissonBoundaryHandler {
             amrex::Array<amrex::LinOpBCType, AMREX_SPACEDIM> const lobc = {

src/python/ImpactX.cpp

@@ -187,6 +187,57 @@ void init_ImpactX (py::module& m)
              },
              "Enable or disable space charge calculations (default: enabled)."
         )
+        .def_property("mlmg_relative_tolerance",
+              [](ImpactX & /* ix */) {
+                  return detail::get_or_throw<bool>("algo", "mlmg_relative_tolerance");
+              },
+              [](ImpactX & /* ix */, amrex::Real const mlmg_relative_tolerance) {
+                  amrex::ParmParse pp_algo("algo");
+                  pp_algo.add("mlmg_relative_tolerance", mlmg_relative_tolerance);
+              },
+              "The relative precision with which the electrostatic space-charge fields should be calculated. "
+              "More specifically, the space-charge fields are computed with an iterative Multi-Level Multi-Grid (MLMG) solver. "
+              "This solver can fail to reach the default precision within a reasonable time."
+        )
+        .def_property("mlmg_absolute_tolerance",
+              [](ImpactX & /* ix */) {
+                  return detail::get_or_throw<bool>("algo", "mlmg_absolute_tolerance");
+              },
+              [](ImpactX & /* ix */, amrex::Real const mlmg_absolute_tolerance) {
+                  amrex::ParmParse pp_algo("algo");
+                  pp_algo.add("mlmg_absolute_tolerance", mlmg_absolute_tolerance);
+              },
+              "The absolute tolerance with which the space-charge fields should be calculated in units of V/m^2. "
+              "More specifically, the acceptable residual with which the solution can be considered converged. "
+              "In general this should be left as the default, but in cases where the simulation state changes very "
+              "little between steps it can occur that the initial guess for the MLMG solver is so close to the "
+              "converged value that it fails to improve that solution sufficiently to reach the "
+              "mlmg_relative_tolerance value."
+        )
+        .def_property("mlmg_max_iters",
+              [](ImpactX & /* ix */) {
+                  return detail::get_or_throw<bool>("algo", "mlmg_max_iters");
+              },
+              [](ImpactX & /* ix */, int const mlmg_max_iters) {
+                  amrex::ParmParse pp_algo("algo");
+                  pp_algo.add("mlmg_max_iters", mlmg_max_iters);
+              },
+              "Maximum number of iterations used for MLMG solver for space-charge fields calculation. "
+              "In case if MLMG converges but fails to reach the desired self_fields_required_precision, "
+              "this parameter may be increased."
+        )
+        .def_property("mlmg_verbosity",
+              [](ImpactX & /* ix */) {
+                  return detail::get_or_throw<bool>("algo", "mlmg_verbosity");
+              },
+              [](ImpactX & /* ix */, int const mlmg_verbosity) {
+                  amrex::ParmParse pp_algo("algo");
+                  pp_algo.add("mlmg_verbosity", mlmg_verbosity);
+              },
+              "The verbosity used for MLMG solver for space-charge fields calculation. "
+              "Currently MLMG solver looks for verbosity levels from 0-5. "
+              "A higher number results in more verbose output."
+        )
         .def_property("diagnostics",
              [](ImpactX & /* ix */) {
                  return detail::get_or_throw<bool>("diag", "enable");