Space charge Mayes IPAC2018 benchmark

docs/source/usage/examples.rst

@@ -35,6 +35,7 @@ This section allows you to **download input files** that correspond to different
    examples/pytorch_surrogate_model/README.rst
    examples/apochromatic/README.rst
    examples/fodo_tune/README.rst
+   examples/ipac2018_mayes/README.rst
 
 
 Unit tests

docs/source/usage/parameters.rst

@@ -667,6 +667,29 @@ Numerics and algorithms
     Currently MLMG solver looks for verbosity levels from 0-5.
     A higher number results in more verbose output.
 
+* ``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

@@ -99,6 +99,39 @@ General
       Currently MLMG solver looks for verbosity levels from 0-5.
       A higher number results in more verbose output.
 
+   .. 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``).

examples/CMakeLists.txt

@@ -894,3 +894,37 @@ add_impactx_test(fodo_tune.py
     examples/fodo_tune/analysis_fodo_tune.py
     OFF  # no plot script yet
 )
+
+# Space charge fields (Gaussian bunch) #################################################
+#
+# w/ space charge
+# copy nominal field data files
+file(COPY ${ImpactX_SOURCE_DIR}/examples/ipac2018_mayes/Ex_Mayes.dat
+        DESTINATION ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/gaussian-SCfields.py)
+file(COPY ${ImpactX_SOURCE_DIR}/examples/ipac2018_mayes/Ez_Mayes.dat
+        DESTINATION ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/gaussian-SCfields.py)
+add_impactx_test(gaussian-SCfields.py
+    examples/ipac2018_mayes/run_fieldplots_ipac2018.py
+      OFF   # ImpactX MPI-parallel
+      ON   # ImpactX Python interface
+    # examples/ipac2018_mayes/analysis_fieldplots_ipac2018.py
+    OFF  # no plot script yet
+)
+
+# Space charge in a coasting Gaussian bunch ############################################
+#
+# w/ space charge
+add_impactx_test(gaussian-SCdrift
+    examples/ipac2018_mayes/input_expanding_ipac2018.in
+      ON   # ImpactX MPI-parallel
+      OFF  # ImpactX Python interface
+    examples/ipac2018_mayes/analysis_expanding_ipac2018.py
+    OFF  # no plot script yet
+)
+add_impactx_test(gaussian-SCdrift.py
+    examples/ipac2018_mayes/run_expanding_ipac2018.py
+      OFF   # ImpactX MPI-parallel
+      ON   # ImpactX Python interface
+    examples/ipac2018_mayes/analysis_expanding_ipac2018.py
+    OFF  # no plot script yet
+)