Add Reset Random Seed Feature (#717)

* Add ResetRandomSeed

* Add doc

* Modify and change location of the code.

* Small fix

* Try to fix an alert

* Try to fix an alert

* Modify based on suggestions

* Use INT_MAX

* Modify based on suggestions.

* Modify based on suggestions.

2 files changed, 31 insertions, 0 deletions

diff --git a/Docs/source/running_cpp/parameters.rst b/Docs/source/running_cpp/parameters.rst
index 73f613a73..0d599a261 100644
--- a/Docs/source/running_cpp/parameters.rst
+++ b/Docs/source/running_cpp/parameters.rst
@@ -44,6 +44,19 @@ Overall simulation parameters
 * ``warpx.verbose`` (`0` or `1`)
     Controls how much information is printed to the terminal, when running WarpX.
 
+* ``warpx.random_seed`` (`string` or `int` > 0) optional
+    If provided ``warpx.random_seed = random``, the random seed will be determined
+    using `std::random_device` and `std::clock()`,
+    thus every simulation run produces different random numbers.
+    If provided ``warpx.random_seed = n``, and it is required that `n > 0`,
+    the random seed for each MPI rank is `(mpi_rank+1) * n`,
+    where `mpi_rank` starts from 0.
+    `n = 1` and ``warpx.random_seed = default``
+    produce the default random seed.
+    Note that when GPU threading is used,
+    one should not expect to obtain the same random numbers,
+    even if a fixed ``warpx.random_seed`` is provided.
+
 Setting up the field mesh
 -------------------------
 
diff --git a/Source/WarpX.cpp b/Source/WarpX.cpp
index 8ffc22ea7..7d6637e38 100644
--- a/Source/WarpX.cpp
+++ b/Source/WarpX.cpp
@@ -340,6 +340,24 @@ WarpX::ReadParameters ()
     {
         ParmParse pp("warpx");
 
+        // set random seed
+        std::string random_seed = "default";
+        pp.query("random_seed", random_seed);
+        if ( random_seed != "default" ) {
+            unsigned long myproc_1 = ParallelDescriptor::MyProc() + 1;
+            if ( random_seed == "random" ) {
+                std::random_device rd;
+                std::uniform_int_distribution<int> dist(2, INT_MAX);
+                unsigned long seed = myproc_1 * dist(rd);
+                ResetRandomSeed(seed);
+            } else if ( std::stoi(random_seed) > 0 ) {
+                unsigned long seed = myproc_1 * std::stoul(random_seed);
+                ResetRandomSeed(seed);
+            } else {
+                Abort("warpx.random_seed must be \"default\", \"random\" or an integer > 0.");
+            }
+        }
+
         pp.query("cfl", cfl);
         pp.query("verbose", verbose);
         pp.query("regrid_int", regrid_int);