Reduce particle shape when a particle approaches the EB (ECP-WarpX#5209)

**Description edited by @RemiLehe**

# Overview

This PR reduces the particle shape to order 1, when the particle gets
closer to the embedded boundary:
<img width="991" alt="Screenshot 2025-01-23 at 8 46 34 AM"
src="https://github.com/user-attachments/assets/2e206606-110e-4018-aedc-385567fe43e7"
/>

This ensures that the particle does not deposit charge in valid cells,
at the time when it is removed, which in turn ensures proper charge
conservation with the electromagnetic solver.

# Implementation

- This PR allocates and initializes a new mask
`eb_reduce_particle_shape` (and `iMultiFab`) that indicates in which
cells to reduce the particle shape.
- The deposition kernels have been modified to use this flag. In order
to make sure that this PR does not affect the performance of the
deposition kernel in the absence of EB, two versions of the deposition
kernel are compiled.

# Tests

This PR adds tests similar to the ones introduced in
ECP-WarpX#5562 to check for charge
conservation near the embedded boundary, but with higher-order shape
factors:

- The 2D tests fail on `development` for shape 2 and 3 but pass on this
PR.
- For some reason, the 3D and RZ tests only fail on `development` for
shape 3 ; they do pass for this PR. It is not clear why the tests do not
fail on `development` with shape 2.

**Note:** For now, this PR only modifies the current deposition (and
only the Esirkepov kernel). A follow-up PR will also modify the charge
deposition.

---------

Co-authored-by: Remi Lehe <remi.lehe@normalesup.org>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Examples/Tests/embedded_boundary_em_particle_absorption/CMakeLists.txt

@@ -13,6 +13,29 @@ if(WarpX_EB)
     )
 endif()
 
+if(WarpX_EB)
+    add_warpx_test(
+        test_3d_embedded_boundary_em_particle_absorption_sh_factor_2  # name
+        3  # dims
+        1  # nprocs
+        inputs_test_3d_embedded_boundary_em_particle_absorption_sh_factor_2  # inputs
+        "analysis.py"  # analysis
+        "analysis_default_regression.py --path diags/diag1"  # checksum
+        OFF  # dependency
+    )
+endif()
+
+if(WarpX_EB)
+    add_warpx_test(
+        test_3d_embedded_boundary_em_particle_absorption_sh_factor_3  # name
+        3  # dims
+        1  # nprocs
+        inputs_test_3d_embedded_boundary_em_particle_absorption_sh_factor_3  # inputs
+        "analysis.py"  # analysis
+        "analysis_default_regression.py --path diags/diag1"  # checksum
+        OFF  # dependency
+    )
+endif()
 
 if(WarpX_EB)
     add_warpx_test(
@@ -26,6 +49,30 @@ if(WarpX_EB)
     )
 endif()
 
+if(WarpX_EB)
+    add_warpx_test(
+        test_2d_embedded_boundary_em_particle_absorption_sh_factor_2  # name
+        2  # dims
+        1  # nprocs
+        inputs_test_2d_embedded_boundary_em_particle_absorption_sh_factor_2  # inputs
+        "analysis.py"  # analysis
+        "analysis_default_regression.py --path diags/diag1"  # checksum
+        OFF  # dependency
+    )
+endif()
+
+if(WarpX_EB)
+    add_warpx_test(
+        test_2d_embedded_boundary_em_particle_absorption_sh_factor_3  # name
+        2  # dims
+        1  # nprocs
+        inputs_test_2d_embedded_boundary_em_particle_absorption_sh_factor_3  # inputs
+        "analysis.py"  # analysis
+        "analysis_default_regression.py --path diags/diag1"  # checksum
+        OFF  # dependency
+    )
+endif()
+
 if(WarpX_EB)
     add_warpx_test(
         test_rz_embedded_boundary_em_particle_absorption_sh_factor_1  # name
@@ -37,3 +84,27 @@ if(WarpX_EB)
         OFF  # dependency
     )
 endif()
+
+if(WarpX_EB)
+    add_warpx_test(
+        test_rz_embedded_boundary_em_particle_absorption_sh_factor_2  # name
+        RZ  # dims
+        1  # nprocs
+        inputs_test_rz_embedded_boundary_em_particle_absorption_sh_factor_2  # inputs
+        "analysis.py"  # analysis
+        "analysis_default_regression.py --path diags/diag1"  # checksum
+        OFF  # dependency
+    )
+endif()
+
+if(WarpX_EB)
+    add_warpx_test(
+        test_rz_embedded_boundary_em_particle_absorption_sh_factor_3  # name
+        RZ  # dims
+        1  # nprocs
+        inputs_test_rz_embedded_boundary_em_particle_absorption_sh_factor_3  # inputs
+        "analysis.py"  # analysis
+        "analysis_default_regression.py --path diags/diag1"  # checksum
+        OFF  # dependency
+    )
+endif()

Examples/Tests/embedded_boundary_em_particle_absorption/analysis.py

@@ -39,7 +39,7 @@
 elif dim == "thetaMode":
     # In RZ: there are issues with divE on axis
     # Set the few cells around the axis to 0 for this test
-    divE_avg[13:19] = 0
+    divE_avg[:, 13:19] = 0
     tolerance = 4e-12
 
 

Examples/Tests/embedded_boundary_em_particle_absorption/inputs_test_2d_embedded_boundary_em_particle_absorption_sh_factor_2

@@ -0,0 +1,11 @@
+# base input parameters
+FILE = inputs_base
+
+geometry.dims = 2
+amr.n_cell = 32 32
+geometry.prob_lo     = -10 -10
+geometry.prob_hi     =  10  10
+boundary.field_lo = pec absorbing_silver_mueller
+boundary.field_hi = pec absorbing_silver_mueller
+
+algo.particle_shape = 2

Examples/Tests/embedded_boundary_em_particle_absorption/inputs_test_2d_embedded_boundary_em_particle_absorption_sh_factor_3

@@ -0,0 +1,11 @@
+# base input parameters
+FILE = inputs_base
+
+geometry.dims = 2
+amr.n_cell = 32 32
+geometry.prob_lo     = -10 -10
+geometry.prob_hi     =  10  10
+boundary.field_lo = pec absorbing_silver_mueller
+boundary.field_hi = pec absorbing_silver_mueller
+
+algo.particle_shape = 3

Examples/Tests/embedded_boundary_em_particle_absorption/inputs_test_3d_embedded_boundary_em_particle_absorption_sh_factor_2

@@ -0,0 +1,11 @@
+# base input parameters
+FILE = inputs_base
+
+geometry.dims = 3
+amr.n_cell = 32 32 32
+geometry.prob_lo     = -10 -10 -10
+geometry.prob_hi     =  10  10  10
+boundary.field_lo = pec pec absorbing_silver_mueller
+boundary.field_hi = pec pec absorbing_silver_mueller
+
+algo.particle_shape = 1

Examples/Tests/embedded_boundary_em_particle_absorption/inputs_test_3d_embedded_boundary_em_particle_absorption_sh_factor_3

@@ -0,0 +1,11 @@
+# base input parameters
+FILE = inputs_base
+
+geometry.dims = 3
+amr.n_cell = 32 32 32
+geometry.prob_lo     = -10 -10 -10
+geometry.prob_hi     =  10  10  10
+boundary.field_lo = pec pec absorbing_silver_mueller
+boundary.field_hi = pec pec absorbing_silver_mueller
+
+algo.particle_shape = 3

Examples/Tests/embedded_boundary_em_particle_absorption/inputs_test_rz_embedded_boundary_em_particle_absorption_sh_factor_2

@@ -0,0 +1,11 @@
+# base input parameters
+FILE = inputs_base
+
+geometry.dims = RZ
+amr.n_cell = 16 32
+geometry.prob_lo     = 0  -10
+geometry.prob_hi     = 10  10
+boundary.field_lo = none absorbing_silver_mueller
+boundary.field_hi = pec absorbing_silver_mueller
+
+algo.particle_shape = 1

Examples/Tests/embedded_boundary_em_particle_absorption/inputs_test_rz_embedded_boundary_em_particle_absorption_sh_factor_3

@@ -0,0 +1,11 @@
+# base input parameters
+FILE = inputs_base
+
+geometry.dims = RZ
+amr.n_cell = 16 32
+geometry.prob_lo     = 0  -10
+geometry.prob_hi     = 10  10
+boundary.field_lo = none absorbing_silver_mueller
+boundary.field_hi = pec absorbing_silver_mueller
+
+algo.particle_shape = 3

Regression/Checksum/benchmarks_json/test_2d_embedded_boundary_em_particle_absorption_sh_factor_2.json

@@ -0,0 +1,24 @@
+{
+  "lev=0": {
+    "divE": 2.4521053721245334e-08,
+    "rho": 0.0
+  },
+  "electron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  },
+  "positron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  }
+}

Regression/Checksum/benchmarks_json/test_2d_embedded_boundary_em_particle_absorption_sh_factor_3.json

@@ -0,0 +1,24 @@
+{
+  "lev=0": {
+    "divE": 2.2059346534892452e-08,
+    "rho": 0.0
+  },
+  "electron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  },
+  "positron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  }
+}

Regression/Checksum/benchmarks_json/test_2d_embedded_boundary_removal_depth_sh_factor_1.json

@@ -0,0 +1,30 @@
+{
+  "lev=0": {
+    "Bx": 0.0,
+    "By": 2.3792992316172512e-15,
+    "Bz": 0.0 ,
+    "Ex": 6.177046470842443e-07,
+    "Ey": 0.0,
+    "Ez": 7.259396011803518e-07,
+    "divE": 2.809306467366024e-07,
+    "rho": 0.0
+  },
+  "electron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  },
+  "positron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  }
+}

Regression/Checksum/benchmarks_json/test_2d_embedded_boundary_removal_depth_sh_factor_2.json

@@ -0,0 +1,30 @@
+{
+  "lev=0": {
+    "Bx": 0.0,
+    "By": 2.3948084603369097e-15,
+    "Bz": 0.0,
+    "Ex": 6.747158562891953e-07,
+    "Ey": 0.0,
+    "Ez": 5.541309886315263e-07,
+    "divE": 2.091715826275267e-07,
+    "rho": 0.0
+  },
+  "electron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  },
+  "positron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  }
+}

Regression/Checksum/benchmarks_json/test_2d_embedded_boundary_removal_depth_sh_factor_3.json

@@ -0,0 +1,31 @@
+{
+    "lev=0": {
+      "Bx": 0.0,
+      "By": 2.379299231617251e-15,
+      "Bz": 0.0,
+      "Ex": 6.177046470842443e-07,
+      "Ey": 0.0,
+      "Ez": 7.259396011803522e-07,
+      "divE": 2.8093064673660275e-07,
+      "rho": 0.0
+    },
+    "electron": {
+      "particle_position_x": 0.0,
+      "particle_position_y": 0.0,
+      "particle_position_z": 0.0,
+      "particle_momentum_x": 0.0,
+      "particle_momentum_y": 0.0,
+      "particle_momentum_z": 0.0,
+      "particle_weight": 0.0
+    },
+    "positron": {
+      "particle_position_x": 0.0,
+      "particle_position_y": 0.0,
+      "particle_position_z": 0.0,
+      "particle_momentum_x": 0.0,
+      "particle_momentum_y": 0.0,
+      "particle_momentum_z": 0.0,
+      "particle_weight": 0.0
+    }
+  }
+

Regression/Checksum/benchmarks_json/test_3d_embedded_boundary_em_particle_absorption_sh_factor_2.json

@@ -0,0 +1,24 @@
+{
+  "lev=0": {
+    "divE": 4.928354322096152e-07,
+    "rho": 0.0
+  },
+  "electron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  },
+  "positron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  }
+}

Regression/Checksum/benchmarks_json/test_3d_embedded_boundary_em_particle_absorption_sh_factor_3.json

@@ -0,0 +1,24 @@
+{
+  "lev=0": {
+    "divE": 4.3355127342920327e-07,
+    "rho": 0.0
+  },
+  "electron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  },
+  "positron": {
+    "particle_position_x": 0.0,
+    "particle_position_y": 0.0,
+    "particle_position_z": 0.0,
+    "particle_momentum_x": 0.0,
+    "particle_momentum_y": 0.0,
+    "particle_momentum_z": 0.0,
+    "particle_weight": 0.0
+  }
+}