Update Sampler API to use getGlobalSamples to avoid ambiguity

(refs idaholab#13906)

framework/include/samplers/Sampler.h

@@ -52,7 +52,7 @@ class Sampler : public MooseObject,
   Sampler(const InputParameters & parameters);
 
   // The public members define the API that is exposed to application developers that are using
-  // Sampler objects to perform calculations, so be very carefull when adding items here since
+  // Sampler objects to perform calculations, so be very careful when adding items here since
   // they are exposed to any other object via the SamplerInterface.
   //
   // It is also important to point out that when Sampler objects, when used, are not const. This is
@@ -63,10 +63,10 @@ class Sampler : public MooseObject,
   /**
    * Return the sampled complete or distributed sample data.
    *
-   * Use these with caution as they can result in a large amount of memory use, the prefered
-   * method for accessing Stampler data is the getNextLocalRow() method.
+   * Use these with caution as they can result in a large amount of memory use, the preferred
+   * method for accessing Sampler data is the getNextLocalRow() method.
    */
-  DenseMatrix<Real> getSamples();
+  DenseMatrix<Real> getGlobalSamples();
   DenseMatrix<Real> getLocalSamples();
   ///@}
 
@@ -77,7 +77,7 @@ class Sampler : public MooseObject,
    * for (dof_id_type i = getLocalRowBegin(); i < getLocalRowEnd(); ++i)
    *     std::vector<Real> row = getNextLocalRow();
    *
-   * This is the prefered method for accessing Sampler data.
+   * This is the preferred method for accessing Sampler data.
    *
    * Calls to getNextLocalRow() will continue to return the next row of data until the last local
    * row has been reached, it will then start again at the beginning if called again. Also, calls
@@ -108,7 +108,7 @@ class Sampler : public MooseObject,
 
 protected:
   // The following methods are the basic methods that should be utilized my most application
-  // developers that are creatign a custom Sampler.
+  // developers that are creating a custom Sampler.
 
   ///@{
   /**
@@ -136,20 +136,21 @@ class Sampler : public MooseObject,
    */
   double getRand(unsigned int index = 0);
 
+  // TODO: Restore this pure virtual after application are updated to new interface
   /**
    * Base class must override this method to supply the sample distribution data.
    * @param row_index The row index of sample value to compute.
    * @param col_index The column index of sample value to compute.
    * @return The value for the given row and column.
    */
-  virtual Real computeSample(dof_id_type row_index, dof_id_type col_index) = 0;
+  virtual Real computeSample(dof_id_type row_index, dof_id_type col_index);
 
   ///@{
   /**
    * Setup method called prior and after looping through distributions.
    *
    * These methods should not be called directly, each is automatically called by the public
-   * getSamples() or getLocalSamples() methods.
+   * getGlobalSamples() or getLocalSamples() methods.
    */
   virtual void sampleSetUp(){};
   virtual void sampleTearDown(){};
@@ -164,7 +165,7 @@ class Sampler : public MooseObject,
    * @param matrix The correctly sized matrix of sample values to populate
    *
    * These methods should not be called directly, each is automatically called by the public
-   * getSamples() or getLocalSamples() methods.
+   * getGlobalSamples() or getLocalSamples() methods.
    */
   virtual void computeSampleMatrix(DenseMatrix<Real> & matrix);
   virtual void computeLocalSampleMatrix(DenseMatrix<Real> & matrix);
@@ -177,7 +178,7 @@ class Sampler : public MooseObject,
    * @param data The correctly sized vector of sample value to poplulate
 
    * This method should not be called directly, it is automatically called by the public
-   * getSamples(), getLocalSamples(), or getNextLocalRow() methods.
+   * getGlobalSamples(), getLocalSamples(), or getNextLocalRow() methods.
    */
   virtual void computeSampleRow(dof_id_type i, std::vector<Real> & data);
 
@@ -204,8 +205,8 @@ class Sampler : public MooseObject,
                                         InputParameters & parameters);
 
   /**
-   * Store the state of the MooseRandom generator so that new calls to getSamples/getLocalSamples
-   * methods will create new numbers. This also handles sample data cache, if enabled.
+   * Store the state of the MooseRandom generator so that new calls to
+   * getGlobalSamples/getLocalSamples methods will create new numbers.
    *
    * The execute() method is called in the init() method of this class and
    * FEProblemBase::executeSamplers; it should not be called elsewhere.
@@ -246,8 +247,8 @@ class Sampler : public MooseObject,
   /// Flag to indicate if the init method for this class was called
   bool _initialized;
 
-  /// Max number of entries for matrix returned by getSamples
-  const dof_id_type _limit_get_samples;
+  /// Max number of entries for matrix returned by getGlobalSamples
+  const dof_id_type _limit_get_global_samples;
 
   /// Max number of entries for matrix returned by getLocalSamples
   const dof_id_type _limit_get_local_samples;
@@ -257,7 +258,7 @@ class Sampler : public MooseObject,
 
   ///@{
   /// PrefGraph timers
-  const PerfID _perf_get_samples;
+  const PerfID _perf_get_global_samples;
   const PerfID _perf_get_local_samples;
   const PerfID _perf_get_next_local_row;
   const PerfID _perf_advance_generator;

framework/src/samplers/Sampler.C

@@ -34,18 +34,18 @@ Sampler::validParams()
   // for size definition, so as start the limits will be based the max of unsigned int. Note,
   // the values here are the limits of the number of items in the complete container. dof_id_type
   // is used just in case in the future we need more.
-  params.addParam<dof_id_type>(
-      "limit_get_samples",
-      0.1 * std::numeric_limits<unsigned int>::max(),
-      "The maximum allowed number of items in the DenseMatrix returned by getSamples method.");
+  params.addParam<dof_id_type>("limit_get_global_samples",
+                               0.1 * std::numeric_limits<unsigned int>::max(),
+                               "The maximum allowed number of items in the DenseMatrix returned by "
+                               "getGlobalSamples method.");
   params.addParam<dof_id_type>(
       "limit_get_local_samples",
       0.1 * std::numeric_limits<unsigned int>::max(),
-      "The maximum allowed number of items in the DenseMatrix returned by getSamples method.");
+      "The maximum allowed number of items in the DenseMatrix returned by getLocalSamples method.");
   params.addParam<dof_id_type>(
       "limit_get_next_local_row",
       0.1 * std::numeric_limits<unsigned int>::max(),
-      "The maximum allowed number of items in the DenseMatrix returned by getSamples method.");
+      "The maximum allowed number of items in the std::vector returned by getNextLocalRow method.");
   return params;
 }
 
@@ -59,10 +59,10 @@ Sampler::Sampler(const InputParameters & parameters)
     _n_cols(0),
     _next_local_row_requires_state_restore(true),
     _initialized(false),
-    _limit_get_samples(getParam<dof_id_type>("limit_get_samples")),
+    _limit_get_global_samples(getParam<dof_id_type>("limit_get_global_samples")),
     _limit_get_local_samples(getParam<dof_id_type>("limit_get_local_samples")),
     _limit_get_next_local_row(getParam<dof_id_type>("limit_get_next_local_row")),
-    _perf_get_samples(registerTimedSection("getSamples", 1)),
+    _perf_get_global_samples(registerTimedSection("getGlobalSamples", 1)),
     _perf_get_local_samples(registerTimedSection("getLocalSamples", 1)),
     _perf_get_next_local_row(registerTimedSection("getNextLocalRow", 1)),
     _perf_advance_generator(registerTimedSection("advanceGenerators", 2)),
@@ -128,16 +128,16 @@ Sampler::execute()
 }
 
 DenseMatrix<Real>
-Sampler::getSamples()
+Sampler::getGlobalSamples()
 {
-  TIME_SECTION(_perf_get_samples);
+  TIME_SECTION(_perf_get_global_samples);
 
-  if (_n_rows * _n_cols > _limit_get_samples)
-    paramError("limit_get_samples",
+  if (_n_rows * _n_cols > _limit_get_global_samples)
+    paramError("limit_get_global_samples",
                "The number of entries in the DenseMatrix (",
                _n_rows * _n_cols,
                ") exceeds the allowed limit of ",
-               _limit_get_samples,
+               _limit_get_global_samples,
                ".");
 
   _next_local_row_requires_state_restore = true;

modules/stochastic_tools/src/vectorpostprocessors/SamplerData.C

@@ -31,7 +31,7 @@ validParams<SamplerData>()
   // params.set<bool>("_is_broadcast") = false;
 
   // Control for
-  MooseEnum method("get_samples get_local_samples get_next_local_row", "get_next_local_row");
+  MooseEnum method("get_global_samples get_local_samples get_next_local_row", "get_next_local_row");
   params.addParam<MooseEnum>(
       "sampler_method",
       method,
@@ -54,18 +54,18 @@ SamplerData::SamplerData(const InputParameters & parameters)
 void
 SamplerData::initialize()
 {
-  dof_id_type n = (_sampler_method == "get_samples") ? _sampler.getNumberOfRows()
-                                                     : _sampler.getNumberOfLocalRows();
+  dof_id_type n = (_sampler_method == "get_global_samples") ? _sampler.getNumberOfRows()
+                                                            : _sampler.getNumberOfLocalRows();
   for (auto & ppv_ptr : _sample_vectors)
     ppv_ptr->resize(n, 0);
 }
 
 void
 SamplerData::execute()
 {
-  if (_sampler_method == "get_samples")
+  if (_sampler_method == "get_global_samples")
   {
-    DenseMatrix<Real> data = _sampler.getSamples();
+    DenseMatrix<Real> data = _sampler.getGlobalSamples();
     for (unsigned int j = 0; j < data.n(); ++j)
       for (unsigned int i = 0; i < data.m(); ++i)
         (*_sample_vectors[j])[i] = data(i, j);
@@ -93,7 +93,7 @@ SamplerData::execute()
 void
 SamplerData::finalize()
 {
-  if (_sampler_method != "get_samples")
+  if (_sampler_method != "get_global_samples")
     for (auto & ppv_ptr : _sample_vectors)
       _communicator.gather(0, *ppv_ptr);
 }

modules/stochastic_tools/test/tests/samplers/monte_carlo/tests

@@ -19,7 +19,7 @@
       input = 'monte_carlo_uniform.i'
       csvdiff = 'monte_carlo_uniform_out_data_0000.csv monte_carlo_uniform_out_data_0001.csv'
       prereq = monte_carlo/uniform
-      cli_args = VectorPostprocessors/data/sampler_method=get_samples
+      cli_args = VectorPostprocessors/data/sampler_method=get_global_samples
 
       detail = 'a uniform distribution replicated across processors,'
     []
@@ -38,7 +38,7 @@
       csvdiff = 'monte_carlo_weibull_out_data_0000.csv monte_carlo_weibull_out_data_0001.csv'
       boost = true
       prereq = monte_carlo/weibull
-      cli_args = VectorPostprocessors/data/sampler_method=get_samples
+      cli_args = VectorPostprocessors/data/sampler_method=get_global_samples
 
       detail = 'a Weibull distribution replicated across processors.'
     []

test/src/userobjects/SamplerTester.C

@@ -19,7 +19,7 @@ validParams<SamplerTester>()
   params.addRequiredParam<SamplerName>("sampler", "The sampler to test.");
 
   MooseEnum test_type(
-      "mpi thread base_global_vs_local rand_global_vs_local rand_global_vs_next getSamples "
+      "mpi thread base_global_vs_local rand_global_vs_local rand_global_vs_next getGlobalSamples "
       "getLocalSamples getNextLocalRow");
   params.addParam<MooseEnum>("test_type", test_type, "The type of test to perform.");
   return params;
@@ -36,8 +36,8 @@ SamplerTester::SamplerTester(const InputParameters & parameters)
 void
 SamplerTester::execute()
 {
-  if (_test_type == "getSamples")
-    _samples = _sampler.getSamples();
+  if (_test_type == "getGlobalSamples")
+    _samples = _sampler.getGlobalSamples();
 
   if (_test_type == "getLocalSamples")
     _samples = _sampler.getLocalSamples();
@@ -51,7 +51,7 @@ SamplerTester::execute()
     mooseAssert(n_processors() == 1, "This test only works on one processor.");
 
     // Get the full set of samples
-    DenseMatrix<Real> global = _sampler.getSamples();
+    DenseMatrix<Real> global = _sampler.getGlobalSamples();
 
     // Iterate through some
     for (dof_id_type i = _sampler.getLocalRowBegin(); i < 7; ++i)
@@ -79,7 +79,7 @@ SamplerTester::execute()
 
   if (_test_type == "rand_global_vs_local")
   {
-    DenseMatrix<Real> global = _sampler.getSamples();
+    DenseMatrix<Real> global = _sampler.getGlobalSamples();
     DenseMatrix<Real> local = _sampler.getLocalSamples();
     if (n_processors() == 1)
     {
@@ -230,7 +230,7 @@ SamplerTester::execute()
 
   if (_test_type == "base_global_vs_local")
   {
-    DenseMatrix<Real> global = _sampler.getSamples();
+    DenseMatrix<Real> global = _sampler.getGlobalSamples();
     DenseMatrix<Real> local = _sampler.getLocalSamples();
 
     if (n_processors() == 1)
@@ -342,15 +342,15 @@ SamplerTester::finalize()
     std::vector<Real> samples;
     if (_communicator.rank() == 0)
     {
-      samples = _sampler.getSamples().get_values();
+      samples = _sampler.getGlobalSamples().get_values();
       vec_size = samples.size();
     }
 
     _communicator.broadcast(vec_size);
     samples.resize(vec_size);
     _communicator.broadcast(samples);
 
-    if (_sampler.getSamples().get_values() != samples)
+    if (_sampler.getGlobalSamples().get_values() != samples)
       mooseError("The sample generation is not working correctly with MPI.");
   }
 }
@@ -361,7 +361,7 @@ SamplerTester::threadJoin(const UserObject & uo)
   if (_test_type == "thread")
   {
     const SamplerTester & other = static_cast<const SamplerTester &>(uo);
-    if (_sampler.getSamples() != other._sampler.getSamples())
+    if (_sampler.getGlobalSamples() != other._sampler.getGlobalSamples())
       mooseError("The sample generation is not working correctly with threads.");
   }
 }

test/tests/samplers/base/errors.i

@@ -24,7 +24,7 @@
   [test]
     type = SamplerTester
     sampler = sample
-    test_type = 'getSamples'
+    test_type = 'getGlobalSamples'
   []
 []
 

test/tests/samplers/base/tests

@@ -138,7 +138,7 @@
 
       detail = "if the number of random number generator seeds is set to zero,"
     []
-    [getSamples_max]
+    [getGlobalSamples_max]
       type = RunException
       input = errors.i
       expect_err = "The number of entries in the DenseMatrix \(3705032704\) exceeds the allowed limit of 429496729."

test/tests/samplers/distribute/execute.py

@@ -44,7 +44,7 @@ def execute(infile, outfile, n_samples, processors, test_type):
     parser.add_argument('-p', '--processors', default=[1,4], type=int, nargs='+', help="List of number of processors to use (default: [1,4]).")
     args = parser.parse_args()
 
-    execute('distribute.i', 'distribute_none', 1, args.processors, 'getSamples')
-    execute('distribute.i', 'distribute_off', args.rows, args.processors, 'getSamples')
+    execute('distribute.i', 'distribute_none', 1, args.processors, 'getGlobalSamples')
+    execute('distribute.i', 'distribute_off', args.rows, args.processors, 'getGlobalSamples')
     execute('distribute.i', 'distribute_on', args.rows, args.processors, 'getLocalSamples')
     execute('distribute.i', 'distribute_row', args.rows, args.processors, 'getNextLocalRow')