Add warning to set zmin and zmax for ion-acc example (#3323)

* Add warning to set zmin and zmax for ions

and also change the ion acceleration example to set these
parameters so that users are aware that memory overflow could
happen for production-size examples

furthermore, correct units in comment after definition of
r0 and Lcut

Replace zmin and zmax with variables for electrons

* Reset checksum for regression test

Reset benchmark for LaserIonAcc2d test because the particle
initialization in the input changed.

3 files changed, 43 insertions, 30 deletions

diff --git a/Docs/source/usage/examples.rst b/Docs/source/usage/examples.rst
index a27b9f3df..cbaaa6bcb 100644
--- a/Docs/source/usage/examples.rst
+++ b/Docs/source/usage/examples.rst
@@ -60,6 +60,12 @@ Laser-ion acceleration
    The resolution of this 2D case is extremely low by default.
    You will need a computing cluster for adequate resolution of the target density, see comments in the input file.
 
+.. warning::
+
+   It is strongly advised to set the parameters ``<species>.zmin / zmax / xmin / ...`` when working with highly dense targets that are limited in one or multiple dimensions.
+   The particle creation routine will first create particles everywhere between these limits (`defaulting to box size if unset`), setting particles to invalid only afterwards based on the density profile.
+   Not setting these parameters can quickly lead to memory overflows.
+
 Uniform plasma
 --------------
 
diff --git a/Examples/Physics_applications/laser_ion/inputs b/Examples/Physics_applications/laser_ion/inputs
index f3659368c..91f8f0704 100644
--- a/Examples/Physics_applications/laser_ion/inputs
+++ b/Examples/Physics_applications/laser_ion/inputs
@@ -76,6 +76,14 @@ algo.load_balance_costs_update = Heuristic
 #################################
 # Target Profile
 #
+
+#   definitions for target extent and pre-plasma
+my_constants.L    = 0.05e-6            # [m] scale length (>0)
+my_constants.Lcut = 2.0e-6             # [m] hard cutoff from surface
+my_constants.r0 = 2.5e-6               # [m] radius or half-thickness
+my_constants.eps_z = 0.05e-6           # [m] small offset in z to make zmin, zmax interval larger than 2*(r0 + Lcut)
+my_constants.zmax = r0 + Lcut + eps_z  # [m] upper limit in z for particle creation
+
 particles.species_names = electrons hydrogen
 
 # particle species
@@ -83,8 +91,10 @@ hydrogen.species_type = hydrogen
 hydrogen.injection_style = NUniformPerCell
 hydrogen.num_particles_per_cell_each_dim = 2 2 4
 hydrogen.momentum_distribution_type = at_rest
-#hydrogen.zmin = -10.0e-6
-#hydrogen.zmax =  10.0e-6
+# minimum and maximum z position between which particles are initialized
+# --> should be set for dense targets limit memory consumption during initialization
+hydrogen.zmin = -zmax
+hydrogen.zmax = zmax
 hydrogen.profile = parse_density_function
 hydrogen.addRealAttributes = orig_x orig_z
 hydrogen.attribute.orig_x(x,y,z,ux,uy,uz,t) = "x"
@@ -96,8 +106,10 @@ electrons.num_particles_per_cell_each_dim = 2 2 4
 electrons.momentum_distribution_type = "gaussian"
 electrons.ux_th = .01
 electrons.uz_th = .01
-#electrons.zmin = -10.0e-6
-#electrons.zmax =  10.0e-6
+# minimum and maximum z position between which particles are initialized
+# --> should be set for dense targets limit memory consumption during initialization
+electrons.zmin = -zmax
+electrons.zmax = zmax
 
 # ionization physics (field ionization/ADK)
 #   [i1] none (fully pre-ionized):
@@ -130,12 +142,7 @@ my_constants.n0    = 30.0      # [n_c]
 #   [material 4] Copper (ion density: 8.49e28/m^3; times ionization level)
 #my_constants.n0    = 1400
 
-# profiles
-#   pre-plasma
-my_constants.L    = 0.05e-6      # [1/m] scale length (>0)
-my_constants.Lcut = 2.0e-6       # [1/m] hard cutoff from surface
-#   core: flat foil, cylinder or sphere
-my_constants.r0 = 2.5e-6        # [m] radius or half-thickness
+# density profiles (target extent, pre-plasma and cutoffs defined above particle species list)
 
 # [target 1] flat foil (thickness = 2*r0)
 electrons.density_function(x,y,z) = "nc*n0*(
diff --git a/Regression/Checksum/benchmarks_json/LaserIonAcc2d.json b/Regression/Checksum/benchmarks_json/LaserIonAcc2d.json
index 36dcc4813..6b9d29fbb 100644
--- a/Regression/Checksum/benchmarks_json/LaserIonAcc2d.json
+++ b/Regression/Checksum/benchmarks_json/LaserIonAcc2d.json
@@ -1,33 +1,33 @@
 {
   "electrons": {
-    "particle_momentum_x": 3.819011093562328e-19,
+    "particle_momentum_x": 3.7558265697785297e-19,
     "particle_momentum_y": 0.0,
-    "particle_momentum_z": 1.6442909854275157e-18,
-    "particle_position_x": 0.008132686101590795,
-    "particle_position_y": 0.030529760810180325,
-    "particle_weight": 2.641331189632942e+17
+    "particle_momentum_z": 1.6241045337016777e-18,
+    "particle_position_x": 0.008080139452222582,
+    "particle_position_y": 0.030470786164249836,
+    "particle_weight": 2.6527193922723818e+17
   },
   "hydrogen": {
-    "particle_momentum_x": 2.2442952799834144e-18,
-    "particle_momentum_z": 1.0841140295639398e-18,
-    "particle_orig_x": 0.008258544921875001,
-    "particle_orig_z": 0.0366896337890625,
-    "particle_position_x": 0.008258183633694481,
-    "particle_position_y": 0.036687836783915156,
-    "particle_weight": 2.701906737218416e+17
+    "particle_momentum_x": 2.230242228305449e-18,
+    "particle_momentum_z": 1.087276856218956e-18,
+    "particle_orig_x": 0.008248212890625,
+    "particle_orig_z": 0.0368645947265625,
+    "particle_position_x": 0.008247833494376897,
+    "particle_position_y": 0.03686279813152423,
+    "particle_weight": 2.6934893377423152e+17
   },
   "lev=0": {
     "Bx": 0.0,
-    "By": 11393530.864665572,
+    "By": 11411806.976599155,
     "Bz": 0.0,
-    "Ex": 2033401599040428.8,
+    "Ex": 2035695789467976.2,
     "Ey": 0.0,
-    "Ez": 316047997346965.6,
-    "jx": 1.634666300264935e+19,
+    "Ez": 323118235034526.9,
+    "jx": 1.656704421803856e+19,
     "jy": 0.0,
-    "jz": 8.884561198935773e+18,
-    "rho": 61730016945.00626,
-    "rho_electrons": 17451988195798.281,
-    "rho_hydrogen": 17441819816491.93
+    "jz": 8.846078579875918e+18,
+    "rho": 61752907894.83176,
+    "rho_electrons": 17451375232572.703,
+    "rho_hydrogen": 17441818436520.373
   }
 }
\ No newline at end of file