[gnuastro-commits] master 2d7c55f: Library (arithmetic): differing envseed for each call to mknoise-*

[Mohammad Akhlaghi]

branch: master
commit 2d7c55f790d485a85534a540c0c44eeec955f796
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Library (arithmetic): differing envseed for each call to mknoise-*
    
    Until now (since previous commit), if the 'mknoise-*' operators were needed
    multiple times (in different columns for example), and a reproducible
    result was required with '--envseed' all the invocations of 'mknoise-*'
    operators would get the same random number generator seed!
    
    With this commit, this problem has been fixed by incrementing the user's
    random number generator seed for every call to the 'mknoise-*'
    operators. As described in the manual, this isn't perfect, so Task 15971
    has been defined as a possible solution (when there are multiple columns
    and the order should not be important).
    
    [1] https://savannah.gnu.org/task/?15971
---
 doc/gnuastro.texi | 14 ++++++++++++--
 lib/arithmetic.c  | 12 ++++++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 2c7d6d0..13fee77 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -12922,8 +12922,10 @@ The internal conversion of C will be used.
 @item mknoise-sigma
 Add a fixed noise (Gaussian standard deviation) to each element of the input 
dataset.
 This operator takes two arguments: the top/first popped operand is the noise 
standard deviation, the next popped operand is the dataset that the noise 
should be added to.
-You can use the @option{--envseed} option to fix the random number generator 
seed (and thus get a reproducible result).
-For more on @option{--envseed}, see @ref{Generating random numbers}.
+
+When @option{--quiet} isn't given, a statement will be printed on each 
invocation of this operator (if there are multiple calls to the 
@code{mknoise-*}, the statement will be printed multiple times).
+It will show the random number generator function and seed that was used in 
that invocation, see @ref{Generating random numbers}.
+Reproducibility of the outputs can be ensured with the @option{--envseed} 
option, see below for more.
 
 For example with the first command below, @file{image.fits} will be degraded 
by a noise of standard deviation 3 units.
 @example
@@ -12953,6 +12955,14 @@ $ echo 5 10 \
 By adding an extra @option{--output=random.fits}, the table will be saved into 
a file called @file{random.fits}, and you can change the @code{i<20} to 
@code{i<5000} to have 5000 rows instead.
 Of course, if your input table has different values in the desired column the 
noisy distribution will be centered on each input element, but all will have 
the same scatter/sigma.
 
+You can use the @option{--envseed} option to fix the random number generator 
seed (and thus get a reproducible result).
+For more on @option{--envseed}, see @ref{Generating random numbers}.
+When using column arithmetic in Table, it may happen that multiple columns 
need random numbers (with any of the @code{mknoise-*} operators) in one call of 
@command{asttable}.
+In such cases, the value given to @code{GSL_RNG_SEED} is incremented by one on 
every call to the @code{mknoise-*} operators.
+Without this increment, when the column values are the same (happens a lot, 
for no-noised datasets), the returned values for all columns will be identical.
+But this feature has a side-effect: that if the order of calling the 
@code{mknoise-*} operators changes, the seeds used for each operator will 
change@footnote{We have defined @url{https://savannah.gnu.org/task/?15971, Task 
15971} in Gnuastro's project management system to address this.
+If you need this feature please send us an email at 
@code{bug-gnuastro@@gnu.org} (to motivate us in its implementation).}.
+
 @item mknoise-poisson
 Add Poisson noise to each element of the input dataset (see @ref{Photon 
counting noise}).
 This operator takes two arguments: the top/first popped operand is the 
background, the next popped operand is the dataset that the noise should be 
added to.
diff --git a/lib/arithmetic.c b/lib/arithmetic.c
index 3e49430..f68bb83 100644
--- a/lib/arithmetic.c
+++ b/lib/arithmetic.c
@@ -668,6 +668,10 @@ arithmetic_mknoise(int operator, int flags, gal_data_t 
*in, gal_data_t *arg)
   unsigned long rng_seed;
   gal_data_t *out, *targ;
 
+  /* Column counter in case '--envseed' is given and we have multiple
+     columns. */
+  static unsigned long colcounter=0;
+
   /* Sanity checks. */
   if(arg->size!=1)
     error(EXIT_FAILURE, 0, "the first popped operand to the '%s' "
@@ -713,6 +717,14 @@ arithmetic_mknoise(int operator, int flags, gal_data_t 
*in, gal_data_t *arg)
   rng=gal_checkset_gsl_rng( (flags & GAL_ARITHMETIC_FLAG_ENVSEED)>0,
                             &rng_name, &rng_seed);
 
+  /* If '--envseed' was called, we need to add the column counter to the
+     requested seed. */
+  if(flags & GAL_ARITHMETIC_FLAG_ENVSEED)
+    {
+      rng_seed += colcounter++;
+      gsl_rng_set(rng, rng_seed);
+    }
+
   /* Print the basic RNG information if requested. */
   if( (flags & GAL_ARITHMETIC_FLAG_QUIET)==0 )
     {